Signing API Requests
Importance of the Date Header
The value of the Date HTTP header is used as part of the request signing process to enforce the temporary state of signed requests. For this reason, the system clock on the client and server sides must be synchronized, up to an allowed time skew of ±360 seconds.
If the server receives an API request with a Date header value that represents more than 30 seconds of time difference (either before or after the server clock), the request will not be accepted.
The X-Zend Signature HTTP Header
In order to send authenticated API requests you are required to send the X-Zend-Signature HTTP header with each request. It must be in the following format:
X-Zend-Signature: <key name>; <signature>
Where <key name> is replaced with the key name, and <signature> is replaced with the calculated request signature.
There can be any number of whitespace characters before or after the separating semicolon.
|
Example:
|
Note: The signature is expected to be 64 characters long, and is cut here for readability purposes. |
Calculating the Request Signature
The request signature is a 64 digit long hexadecimal number with digits a-f in lower case, calculated using the following method:
- Concatenate the following values in order, separated by a colon (:), into a single string:
- The exact value of the Host HTTP header. In most cases this will be a string in the form "<host>:<port>". In some cases the colon and port are omitted. In any case, if the port is included in the Host header sent in the request, it must be included in the generated string.
- The Request URI, which is the path part of the full request URL, without the query string or host name.
- The exact value of the User-Agent request header.
- The exact value of the Date request header.
- Hash the generated string with the HMAC/SHA-256 function using the secret API key to obtain the request signature.
Examples
Creating a Signature
|
To create a signature:
|
|
Additional Values
|
When sending the following API request:
Using a key named “angel.eyes” with the following value:
The request parameters to be signed, concatenated into a string is:
From this value, an HMAC/SHA-256 signature will be calculated using the API key. For example using the hash_hmac() PHP function:
The final request, including the added X-Zend-Signature header, is (lines are broken for readability):
|
The server then proceeds to generate the same signature, based on the same data and same secret key. If the two signatures match, the request will be accepted. |