As part of ongoing work to continually improve Shippit’s security, we are requesting our customers to switch to our latest, recommended mechanism for authentication.
As such we are retiring our previous method, and requesting our customers switch to our preferred mechanism.
This article outlines the necessary technical changes required for custom integrations to transition away from the less secure mechanism, to Shippit’s recommended authentication mechanism.
For specific platform integrations, please read our support documentation.
The deprecated authentication mechanism
Shippit’s API currently allows API consumers to provide their authentication token in two different ways. The first way has been determined to be less secure than the alternative. This less secure mechanism can be described as “include the authentication token as a URL parameter”.
For example, using this method would see API calls made to a URL that contains the secret API Key:
Where XXXXXXX would be the secret API key supplied by Shippit.
This technique is deemed less secure as there is an increased risk that this secret can be leaked by humans via copy-paste. There is also an increased risk of client and Shippit’s systems leaking the authentication token to third-party tools. Because of this risk, Shippit has deprecated this mechanism and will be retiring it in 2021.
The preferred authentication mechanism
The preferred mechanism is described in our developer documentation.
To make requests to the API, the authentication token should be passed in the
HTTP authorization request header field. This should follow the structure:
Authorization: Bearer XXXXXXX
Where XXXXXXX is the secret API key supplied by Shippit.
All modern HTTP programming libraries will support setting HTTP request headers. Advice for specific libraries/languages goes beyond the scope of this document.
Testing your changes in Shippit's staging environment
To test your changes safely before the production release, Shippit provides a staging environment that can be used as a sandbox. To make API calls to this environment, use https://api.staging.shippit.com in place of the production URL.
If you require an account in our staging environment, please contact our support team at firstname.lastname@example.org
API Key Access
API Keys can be obtained via the Shippit user interface by users with appropriate privileges. See our developer documentation for more information.
Whilst doing these authentication updates, there is this additional useful and related document for improving your API request headers. These optional parameters are strongly encouraged as a means to improve Shippit's support to your integration.