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.

Example:
POST https://v2.convertapi.com/token/create?Secret=XXXX&RequestCount=3&Lifetime=10000&Count=2
  • 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).
Response (also available in XML format):
{
    "Tokens": [
        {
            "Id": "4X4RxBGP",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
        },
        {
            "Id": "mKRuP5zW",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
        }
    ]
}
Token use example:
POST https://v2.convertapi.com/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.

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

Usage example
POST https://v2.convertapi.com/docx/to/pdf?ApiKey=0000000000&Token=E1vYBWy7TAabnFSReCTJGiFUx3xoCJiyIwbPWvuRpcM= 
C# code example to generate token:
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);
        var base64String1 = Convert.ToBase64String(bytes);
        var base64String = base64String1;
        return new string(base64String.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;
    }

    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 Convert.ToBase64String(encryptedTokenData);
    }
}

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:
  • 4041 - Invalid user credentials - bad secret.