Support
Using OAuth 2.0 to Access Maersk APIs
Prerequisites
1. Client ID and Client Secret: You must have your client ID and client secret for the App you created to access our API Product(s). Your client ID is the Consumer-Key that was automatically generated when you created your App. If you don't have these credentials, please refer to our Getting Started Guide or contact our support team.
2. API Endpoint for Token: The URL where you will send your authentication request to obtain the token. Ensure you use the endpoint that matches the environment in which you plan to call the API.
3. Required Libraries or Tools: Depending on your programming environment, you may need libraries or tools that can send HTTP requests.
Step-by-step Guide
1. Send a POST request to the access token endpoint of the Maersk authorisation server.
Pre-Production (Stage) Environment
curl --location 'https://api-stage.maersk.com/oauth2/access_token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={appConsumerKey}' \
--data-urlencode 'client_secret={appClientSecret}'
Production Environment
curl --location 'https://api.maersk.com/oauth2/access_token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={appConsumerKey}' \
--data-urlencode 'client_secret={appClientSecret}'
2. Include the Access Token from Step 1 in the Header of the Request to the API
--header 'Authorization: Bearer {access_token}' \
--header 'Consumer-Key: {appConsumerKey}' \
Best Practices
1.Keep your Consumer-Key and Client Secret confidential: Avoid exposing these credentials in client-side code or public repositories.
2.Handle token expiry: Tokens obtained using the client credentials flow have a finite lifetime of 2 hours. Ensure your application handles token expiry gracefully, obtaining a new token when needed.
3.Secure your communications: Always use HTTPS endpoints to ensure your credentials and tokens are transmitted securely.
Common Errors
1. If you have requested access to one or more API Products but have not received a notification that your access is approved, this error means your Client ID has not been provisioned in the Maersk authentication server. If you have received a notification that your access is approved and you receive this error, please contact our support team for assistance.
HTTP/1.1 400 Bad Request
{
"error_description" : "Client authentication failed",
"error" : "invalid_client"
}
2. This error is returned by the Maersk authorisation server if your access token has been misconfigured in our Identity Access Management System. If you receive this error, please contact our support team for assistance.
HTTP/1.1 400 Bad Request
{
"error_description" : "Client authentication failed",
"error" : "invalid_client"
}
3. This error indicates that your request to the Maersk authorisation server is missing the Content-Type in the header of your request. Be sure to include --header 'Content-Type: application/x-www-form-urlencoded’ \ in the header of your request.
HTTP/1.1 400 Bad Request
{
"error_description" : "Client authentication failed",
"error" : "invalid_client"
}
4. This error generally indicates that you have used the GET method for your request, which is not supported by target resource. Please use the POST method to request your access token.
HTTP/1.1 400 Bad Request
"fault" : {
"faultstring" : "Received 405 Response without Allow Header",
"detail" : {
"errorcode" : "protocol.http.Response405WithoutAllowHeader"
}
}