All requests to the API must be signed to ensure only entities with permission can use the API. The API supports authentication for users and for applications, as well as user sessions within an application.
All types of authentication consist of signing the request string with a key, with the key depending on the specific type of authentication used. The information on this page describes how to build the request string to sign, how to sign a request string, and which key to use for each of the supported authentication types.
Building request strings¶
The request string is a string representation of the entire request sent to the API. To build the request string, concatenate the request path, a question mark (?), the request parameters as a HTTP query-string, an ampersand (&), and finally the request arguments as a HTTP query-string. The included parameters must contain all parameters that will be sent, including the authentication_type, timestamp, and other authentication parameter, but excluding the signature parameter.
For example, consider the following request, which will be signed by a user:
Note that there is no authentication_type parameter, since user authentication is the default authentication type. The request string for this request is as follows:
To sign requests, some parameters must be added to the request before building the request string.
The authentication_type parameter must contain the type of authentication to use, being either user or application. This parameter can be omitted when user authentication is used, since that is the default type of authentication.
The timestamp parameter must contain the UNIX timestamp of the moment that the request is executed. This time is allowed to be slightly off, but errors of more than 5 minutes are not allowed.
The request string must be constructed with these parameters added to the request.
Once the request string has been constructed, the signature can be calculated. The signature is obtained by signing the request string with the relevant key using HMAC-SHA1, and retrieving the result as a lowercase hexidecimal string. Standard library functions for HMAC exist in many programming languages; see the list below for some examples. Be sure to specify SHA1 as the hashing algorithm to use where required.
- .NET Framework 4.5: HMACSHA1 Class
- Java 7: SecretKeySpec class using the HmacSHA1 algorithm
- PHP: hash_hmac function using the sha1 algorithm
- Python 2: hmac module using the hashlib.sha1 digest
- Python 3: hmac module _using the hashlib.sha1 digest
For example, consider signing the request string as obtained in the previous section:
Let the key to sign this request with be pre-shared-key. The resulting signature is cd10d5509566abd275583c3a29bae9e32352fb08. This must be the value of the signature parameter, resulting in the following signed request:
Note that we will rate-limit from your IP if you supply the wrong key too many times in a short period of time. We will send a statuscode of STATUS_RATE_LIMITED in that case.
There are a number of different authentication types that can be used. The authentication type determines which parameters are required for authentication, and which pre-shared key to use. The authentication type used is determined by the value of the authentication_type parameter, which can be one of the following:
- user: authenticating with a user (default)
- application: authenticating with an application, optionally including a user session
To use user authentication, set the authentication_type parameter to user. The user ID of the user which executes the request must be passed in the user parameter. The request must be signed using the pre-shared key of the user with the given user ID.
To use application authentication, set the authentication_type parameter to application. The application ID of the application which executes the request must be passed in the application parameter. The request must be signed using the pre-shared key of the application with the given application ID.
To authenticate using an active session, the session ID must be passed in the session parameter. The request must then be signed using a key which is the concatenation of the application pre-shared key and the session key. For example, if the application pre-shared-key is ApplicationKey and the session key is SessionKey, the request must be signed using the key ApplicationKeySessionKey. For more information on creating and using sessions, refer to the documentation of the session command.