General: Authentication
Authentication
The API supports different authentication methods. For security reasons, some of the authentication methods are disabled by default. They can be enabled per access key in the API control panel. In the examples below we are using our timeservice to showcase the required service parameter, but the same parameter can be replaced by the name of any of our API Services.
- HMAC based
- HTTP Basic authentication (disabled by default)
- User/Password in URL (disabled by default)
HMAC Based Authentication
Recognized parameters| Name | Description | Required |
|---|---|---|
| accesskey | The access key for the request sender. This parameter identifies the account that will be charged for the request. Access keys can be created in the API control panel. Additionally, the API control panel allows to set certain preferences and restrictions per access key. Type: String Example: | Yes |
| expires | The date and time at which the signature for this request will expire. After this time, the request will be declined. This time stamp cannot be more than 24 hours ahead from the time the request is submitted. Type: Date/Time in ISO 8601 format (see [ISO8601]) Example: Condition: Either the time stamp or the expires parameter have to be supplied. | Conditional |
| timestamp | The date and time at which the request has been signed. If this timestamp does not match server time (with a grace period of +/- 15 minutes), the request will be declined. Type: Date/Time in ISO 8601 format Example: Condition: Either the timestamp or the expires parameter have to be supplied. | Conditional |
| Signature | The signature for the request. The signature is created by applying the HMAC-SHA1 ([RFC 2104]) function to a concatenation of the access key, the called service name and the signature timestamp or expiry timestamp. The resulting data has to be encoded with the Base64 method. See Creating a Signature for more details. Type: String Example: | Yes |
Creating a Signature
Following is a step-by-step guide for how to create a signature. If you want a more interactive guide please see our HMAC signature calculator.
First decide if you want to sign a single request by using the current timestamp, or if you want to pre-sign several requests. Get the current system time and create either the timestamp or the expires parameter. The time in the timestamp can be either UTC (indicated by appending the character Z to the timestamp), or in local time (in this case, the difference to UTC has to be indicated by appending +HH:MM to the timestamp).
- Concatenate your access key, the service name and either the request timestamp or the expiry timestamp together. Do not use any characters to separate them.
- Use the newly created string and your secret key to create an RFC 2104 compliant signature.
Use the SHA-1 hash algorithm for the calculation. A detailed description of the HMAC calculation can be found in [RFC 2104]. - Apply the Base64 encoding (defined e.g. in [RFC 2104]) to the calculated binary signature.
Example Signature and Request. Assuming the following values, an example signature and the resulting request URL will be shown:
- Access key:
NYczonwTxv- Secret key:
x4whvXnG7cCOBiNBoi1r- Request timestamp:
2011-04-15T15:43:46Z- Service name:
timeservice
- Concatenate access key, service name and request timestamp:
NYczonwTxvtimeservice2011-04-15T15:43:46Z. - Calculate the HMAC by using the SHA-1 hash algorithm. Make sure that the result actually is binary data and not a hexadecimal representation of the resulting data.
- Apply Base64 encoding to the resulting binary data:
OlTRdhobJdUPDyM89lu0xKe4REY=. - Construct the request. Remember to apply URL encoding to the parameter values in case your toolkit does not perform this operation automatically for you:
https://api.xmltime.com/timeservice?accesskey=NYczonwTxv×tamp=2011-04-15T15%3A43%3A46Z&signature=OlTRdhobJdUPDyM89lu0xKe4REY%3D&further parameters….
Many popular programming languages and scripting toolkits offer support for HMAC signing out of the box, or make it very easy to add support for it. See our chapter on Sample Implementations for examples on how to construct and submit an API request using these.
HTTP Basic Authentication
The services also supports the Basic authentication scheme as defined in section 11.1 of [RFC 2104]. Please be aware that this authentication method does not provide sufficient measures to protect your credentials. For this reason, you have to specifically enable it per access key on the access key pages.
To use this authentication method, pass your access key as user name and the secret key as password to your toolkit.
Example Shell Commands
Assuming the following values, example requests with curl and wget are shown:
- Access key:
NYczonwTxv- Secret key:
x4whvXnG7cCOBiNBoi1r- Service name:
timeservice
$ curl --user NYczonwTxv:x4whvXnG7cCOBiNBoi1r https://api.xmltime.com/timeservice?further parameters… $ wget --user=NYczonwTxv --password=x4whvXnG7cCOBiNBoi1r https://api.xmltime.com/timeservice?further parameters… User/Password in URL
This is the easiest authentication method available. Please be aware that this authentication method does not provide sufficient measures to protect your credentials. For this reason, you have to specifically enable it per access key – this can be done in the access key pages.
Recognized parameters| Name | Description | Required |
|---|---|---|
| accesskey | The access key for the request sender. This parameter identifies the account that will be charged for the request. Access keys can be created in the API control panel. Additionally, the API control panel allows to set certain preferences and restrictions per access key. Type: String Example: | Yes |
| secretkey | The secret key associated with the access key. Type: String Example: | Yes |
Example Request
Assuming the following values, an example request is shown below:
- Access key:
NYczonwTxv- Secret key:
x4whvXnG7cCOBiNBoi1r- Service name:
timeservice
https://api.xmltime.com/timeservice?accesskey=NYczonwTxv&secretkey=x4whvXnG7cCOBiNBoi1r&further parameters…