Api Authentication

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:

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
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:

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);
    }
}