Authentication API documentation

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

To authenticate to v2.convertapi.com there are two options:

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

Token

Request Token

Token request accepts URL query parameters.

  • Secret - your secret.
  • RequestCount - restrict how many requests can be made using single token (default is 1).
  • Lifetime - restrict how many seconds token is valid (default is 1h).
  • Count - how many tokens will be received by this request (default is 1).
Get token from server example
Request:
POST https://v2.convertapi.com/token/create?Secret=XXXX&RequestCount=3&Lifetime=10000&Count=2
Response:
{
    "Tokens": [
        {
            "Id": "4X4RxBGP",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
        },
        {
            "Id": "mKRuP5zW",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
        }
    ]
}
Token usage example
Request:
POST https://v2.convertapi.com/convert/doc/to/pdf?Token=4X4RxBGP

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 time stamp format.
    • userIp - IP address that can use this token (can be blank if token not restricted).
    • requestCount - request count that can be made using this token.
  • Encrypt token string with AES encryption algorithm using your secret as encryption key, initialization vector (IV) should be "//convertapi.com".
  • Encode encrypted string with Base64 algorithm.
Token generation code example
C#:
public static class SelfGeneratedToken
{
    private const int TokenLength = 8;

    private static string GenerateUniqueString(int length)
    {
        var bytes = new byte[100];
        var rng = RandomNumberGenerator.Create();
        rng.GetBytes(bytes);
        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("//convertapi.com"),
            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 ApiKey parameter. ApiKey can be found in Control Panel.

Self generated token usage example
Request:
POST https://v2.convertapi.com/convert/docx/to/pdf?ApiKey=0000000000&Token=E1vYBWy7TAabnFSReCTJGiFUx3xoCJiyIwbPWvuRpcM=

HTTP Response Codes

200

Internal codes provided in response body:
  • 2000 - Token created successfully.
  • 2001 - Token canceled successfully.

404

Internal codes provided in response body:
  • 4040 - Invalid user credentials - bad secret.
  • 4041 - Invalid user credentials - bad token.
  • 4042 - Invalid user credentials - bad self generated token.
  • 4043 - User credentials not set, secret or token must be passed.
  • 4044 - The conversion seconds balance reached zero and no more conversions can be done. Please order more seconds and resume service.
  • 4045 - User inactive.