Authentication and validation
As always with an API, we will need to authenticate the request and verify that the request is valid!
This api uses the HTTP basic authentication protocol, but does not use the standard username and password.
Instead, the username and password are constructed by using keys and a calculated hash.
First, you will need to obtain a secret and public key for your plugin. These can easily be created in the frontend or (if allowed) using the api endpoint.
With these keys a token can be requested on the keys endpoint, which also registers your plugin the first time this request is done.
Once this token is obtained, this is used for all other authentication by creating the hash that is needed for the authentication protocol.
When handling keys, please keep the following 'rules' in mind:
- Any key is unique in our entire system.
- The secret and public keys that are generated are bound to the client and application they are created with.
- A key pair can only be used for exactly 1 install (or: running plugin).
- It is only possible to store shipments for the account and application that created the keys (unless ofcourse your plugin is registered as an application).
- The token will have an expiry date. After this date a new token has to be requested.
- The token can be made invalid in the app before the expiry date for a number of reasons, you can also do this yourself in the key management page.
Authenticating and validating your API request
Authenticating any request is done by using basic http authentication, but instead of the normal username and password the api expects the 'username' to be the public or token key and the 'password' to be a hash that is calculated to verify the data.
The decision to use either your public key or the token depends on the endpoint that is used..
Basically, the public key is only used to obtain a token key. This token key is used in every other request.
For the basic http authentication a calculated hash is used as the password. This has is calculated in the following steps:
- Put the data (json, document, etc) that is about to be sent in 1 string. An empty string is also valid.
- Prepend the token (or public key) to this string
- Calculate the hash by using hmac sha256 using the secret key, making sure the outcome is a base64 encoded string. The function for this differs in any programming language, please refer to the examples and the documentation for that language.
- Make sure the hash has no padding at the end. If it has, remove it.
The result is the password for the http authentication.
The api will first use the given http authentication to look up the keys to use. Next it will do the exact same calculations with the found keys. If the result does not match, the request is considered invalid and a http error code will result.
If the calculated hash matches the given hash, the request is considered ok and further processing will commence.
Because of this, make sure that with any method (GET for instance) that does not required data to make sure that the calculation is done with no data, else your request will surely fail!
Token key
An entire request (except to the keys endpoint) is best done in the following steps:
- Check if your token is still valid by checking the expiry date. If not valid, request a new one.
- Create a hmac sha256 hash from a concatenation of: the key used as the username for http and the JSON string you intend to send, even if the string is empty. Encode the hash in base64 without padding.
- Do the request (using the token as http username and hash as http password)
- If you receive a http 401 Not Authorized, it might be that the token is invalidated in the API. Try to get a new token.
- If the token request succeeds, redo the request you intended to do.
- If you get a 401 Not Authorized error again, there is a problem with your keys or your account. Please call your contactperson for further help in this case.
Key Where to obtain Application/plugin key Requested by calling your contactperson (see Before you start) Public key Created on the key management page in the application or (if allowed) using the /KEYS/ / endpoint. Secret key Created on the key management page in the application or (if allowed) using the /KEYS/ / endpoint. Token Requested by your plugin from the API using the /KEYS/ / endpoint
1. Put all data in a string 2. Add the token (or public key) in front of the string 3. Create a HMAC SHA256 hash of the string using the secret key 4. Encode the hash as base64. Some languages can do step 3 and 4 at once.