The following operations are allowed in the Authentication API:

An access token is valid for a certain amount of time before it expires. This limit is currently set to 60 minutes. When it expires, the requested resource will throw the following error: 'Access token expired'. At this time a new access token should be requested. A new access token is not needed for each request.

We recommend that you refresh the access token periodically (~15 mins to 30 mins) so that none of the resource requests receive an error due to an expired access token. We will inform clients if the access token expiry is changed to less than 30 minutes.

Workflow

• The following fields needs to be sent as form parameters - client_id, client_secret and grant_type

• Sending the request will return an access_token in the response

The access token is a Bearer token hence it must be sent with every resource request using the Bearer preprended to the token itself and separated by a space.

• For example, if the access token value is edEB6SlC8wafnWgAlgqxagATPF0F, then the token must be passed in all resource requests as a header as follows -

Header name: Authorization
Header value: Bearer edEB6SlC8wafnWgAlgqxagATPF0F
 

Here is a sample request

POST /auth/v4/accesstoken HTTP/1.1 
Host: api-sandbox.dhlecs.com 
Content-Type: application/x-www-form-urlencoded 
grant_type=client_credentials 
client_id=<your client id here> 
client_secret=<your client secret here>

Note that the request contains a field called grant_type with a value of client_credentials. The grant_type is sent in the body with the Content-Type of application/x-www-form-urlencoded. This is mandatory for successful authentication and getting an access_token. Please refer here for more information on grant types.

Here is a sample good response

{
   "access_token": "OGH0T5hPVJ2oL0DYhRfYJgJMJYhC",
   "client_id": "G8PaGaNdIg5CS5q5mAibmJ9jywTFiO97",
   "token_type": "Bearer",
   "expires_in": 3600
}

Here is a sample bad response

{
   "type": "https://api-sandbox.dhlecs.com/docs/errors/400.0000005",
   "title": "Invalid credentials"
}