API KEY Authentication

Convert API supports two methods of API key authentication:

1. Request Signing (HMAC)

When using request signing, Convert API uses the Hash-based message authorization code (HMAC).
Instead of having passwords that need to be sent over, we actually use Signing Method for API request validation.
When you send HTTP requests to Convert, you sign the requests so that Convert can identify who sent them.
So every request should contain Signature, calculated with the help of a Secret Key, Request URL, Request payload, Request Expiration time.

Three headers have to be sent with each request in order for the request to be authenticated correctly by Convert API:

• Convert-Application-ID: This is the ID you get from your account corresponding to the application created inside Convert App.
• Expires: This is a UNIX timestamp after which the request signing expires. The closer in future the timestamp is, the sooner the request signature would be invalidated and the more secure would be
• Authorization: The value of this one is as follows: Convert-HMAC-SHA256 Signature=[generated_hash]; The [generated_hash] is a request signature calculated applying sha256 hashing algorithm on ApplicationID, ExpiresTimestamp, RequestURL, RequestBody.

What could go wrong with request signing authorization? APP ID and APP Secret are right, but it is still UNAUTHORIZED!

• Check your system time - the time of the system where signature is generated
• Check the request duration between client and API and provide larger expiration time if it takes longer so that signature does not expire before reaching validation on Convert's servers
• Make sure that stringified payload and Sign String are correct and do not contain additional spaces. For Javascript just use JSON.stringify(request) for request payload. For php use additional flags for json_encode: json_encode($request, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)).
• Make sure you are using HMAC SHA256 to calculate the signature and provide this method (Convert-HMAC-SHA256) in the Authorization header value
• Make sure that nothing changes the payload after signature generation but before sending it

Example of the request signing signature generation in Javascript:

var SignString  = ApplicationID + "\n" + ExpiresTimestamp + "\n"  + RequestURL + "\n" + RequestBody;
var hash = CryptoJS.HmacSHA256(SignString, ApplicationSecretKey);
var hashInHex = CryptoJS.enc.Hex.stringify(hash);
var Authorization = "Convert-HMAC-SHA256 Signature=" + hashInHex;

For the above example, the Authorization header would be "Authorization: Convert-HMAC-SHA256 Signature=${Authorization}"

2. Secret Key

A simpler authentication method using a shared secret key. This method requires only a single header:

• Authorization: Include the key ID and key secret as a Bearer token in the format: Bearer KEY_ID:KEY_SECRET

The secret key method is easier to implement while still providing strong security. However, request signing provides additional security through request expiration and payload validation.

Using the "Try It" playground

The Secret Key method is the one to use when testing endpoints from the "Try It" panel on this page — select it in the authentication dropdown and paste KEY_ID:KEY_SECRET as the Bearer token.

Request Signing (HMAC) cannot run inside the playground: the signature must be computed at request time from the Application ID, Secret, URL, body, and Expires timestamp, and no OpenAPI-driven playground can do that on its own. To enable HMAC in "Try It" we would need a custom JavaScript auth flow (a Readme.io Enterprise-plan feature); on the current Startup plan it is not available, so HMAC should be exercised via curl, Postman, or an SDK instead.