Authentication
Autentication Methods
The ConvertAPI supports the following authentication methods. Note that these methods are checked in the order shown below, so if multiple authentication methods are provided, the user used to authenticate the REST API call will be the one with the lowest order in the following list:
Order | Authentication Method | Persistence |
---|---|---|
1 | URL Parameters | Stateless |
2 | Basic Authentication | Stateless |
URL Parameters
curl -X GET https://v2.convertapi.com/user?Secret=your_api_secret
Basic Authentication
curl -X GET https://v2.convertapi.com/user -H "Autentication:Basic your_api_key your_api_secret"
Autentication Credentials
In this section, we're going to focus on the ConvertAPI authentication credentials.
There are two options to authenticate to v2.convertapi.com
:
-
Secret
- can authenticate requests from the code that is not accessible for the user (server-side software like PHP). -
Token
- can authenticate requests from the code accessible for the user (client-side software like JavaScript). Tokens are created by using/token
endpoint or generated in control panel. -
ApiKey
- is used for basic authentication and self generated tokens.
Api Secret, Api Key and generated Tokens can be found in Control Panel.
Token
Request Token
The token request accepts URL query parameters. In order to make a virtually non-expiring token that can be used instead of a secret key to authenticate your requests, simply set the Lifetime and RequestCount to it's highest values.
-
Secret
- your api secret key. -
RequestCount
- restrict how many requests can be made using a single token. The default is 1 and the maximum can be set to 999999999 requests. -
Lifetime
- the token lifetime in seconds. The default is 3600 seconds(1h) and the maximum can be set to 315569520 seconds (10 years). -
Count
- specify how many tokens will be created by the request, the default is 1 token.
curl -X POST "https://v2.convertapi.com/token/create?Secret=your_api_secret&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
curl -X POST "https://v2.convertapi.com/convert/docx/to/pdf?Token=4X4RxBGP" \
-H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
-F "file=@C:\document.docx;filename=document.docx;type=*/*"
Delete token
You can leave the token to expire or delete it right away. Please note: your secret key must be provided in the delete request to prevent malicious requests.
curl -X DELETE "https://v2.convertapi.com/token/u3XmwBoA?Secret=your_api_secret"
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 "//convertapi.com".
- 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();
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 the ApiKey parameter. ApiKey can be found in Control Panel.
Token usage
curl -X POST "https://v2.convertapi.com/convert/docx/to/pdf?ApiKey=your_api_key&Token=E1vYBWy7TAabnFSReCTJGiFUx3xoCJiyIwbPWvuRpcM=" \
-H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
-F "file=@C:\document.docx;filename=document.docx;type=*/*"
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.
-