In this section, we're going to focus on the basics of two ConvertAPI authentication methods.

There are two options to authenticate to

  • Secret - Can be used to authenticate requests from the code that is not accessible for the user (server-side software like PHP). A Secret key can be found in the Control Panel.
  • Token - Can be used to authenticate requests from the code that is accessible for the user (client-side software like JavaScript on the web browser). Tokens can be requested by the API call or generated using Secret.


Request Token

The token request accepts URL query parameters.

  • Secret - your secret.
  • RequestCount - restrict how many requests can be made using a single token (default is 1).
  • Lifetime - restrict how many seconds token is valid (default is 1h).
  • Count - specify how many tokens will be received by this request (default is 1).
    "Tokens": [
            "Id": "4X4RxBGP",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
            "Id": "mKRuP5zW",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"

Token usage


Delete token

You can leave the token to expire or delete it right away.


Generate Token

Token generation algorithm steps:

  • Create token string: tokenUuid|expireTimeStamp|userIp|requestCount.
    • tokenUuid - random 8 bytes alphanumeric string.
    • expireTimeStamp - token expiration time in Unix timestamp format.
    • userIp - IP address that can use this token (leave blank if you don’t want to restrict).
    • requestCount - request count that can be made using this token.
  • Encrypt token string with AES encryption algorithm using your secret as the encryption key, an initialization vector (IV) should be "//".
  • Encode an encrypted string using the Base64 algorithm.

Token generation code example

public static class SelfGeneratedToken
    private const int TokenLength = 8;

    private static string GenerateUniqueString(int length)
        var bytes = new byte[100];
        var rng = RandomNumberGenerator.Create();
        return new string(Convert.ToBase64String(bytes).Where(char.IsLetterOrDigit).Take(length).ToArray());

    private static AesCryptoServiceProvider AesCryptoServiceProvider(string secret)
        var aesCsp = new AesCryptoServiceProvider
            BlockSize = 128,
            IV = Encoding.ASCII.GetBytes("//"),
            Key = Encoding.ASCII.GetBytes(secret)
        return aesCsp;

    private static string UrlBase64Encode(byte[] bytes)
        return Convert.ToBase64String(bytes).Replace('+', '-').Replace('/', '_').TrimEnd('=');

    public static string Create(string secret, TimeSpan validityDuration, string userIp, int? requestCount)
        var expireTimeStamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + validityDuration.TotalSeconds;
        var tokenUuid = GenerateUniqueString(TokenLength);
        var tokenDataString = $"{tokenUuid}|{expireTimeStamp}|{userIp}|{requestCount}";

        var tokenDataBytes = Encoding.ASCII.GetBytes(tokenDataString);
        var aesCsp = AesCryptoServiceProvider(secret);
        var encryptedTokenData = aesCsp.CreateEncryptor().TransformFinalBlock(tokenDataBytes, 0, tokenDataBytes.Length);
        return UrlBase64Encode(encryptedTokenData);

Self generated token must be used together with the ApiKey parameter. ApiKey can be found in Control Panel.

Token usage


HTTP Response Codes

  • 200 Ok

    • 2000 Token created successfully.
    • 2001 Token deleted successfully.
  • 401 Unauthorized Authentication failure.

    • 4010 Invalid user credentials - bad secret.
    • 4011 Invalid user credentials - bad token.
    • 4012 Invalid user credentials - bad self generated token.
    • 4013 User credentials not set, secret or token must be passed.
    • 4014 User inactive.