Api Authentication

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).

{
    "Tokens": [
        {
            "Id": "4X4RxBGP",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
        },
        {
            "Id": "mKRuP5zW",
            "ValidUntil": "2017-08-22T16:45:24.6184076Z"
        }
    ]
}

POST https://v2.convertapi.com/doc/to/pdf?Token=4X4RxBGP

Generate Token

• 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=

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