How to use Access Token to access DHL eCommerce Global APIs

DHL eCommerce use the OAuth 2.0 protocol for authentication and authorization. DHL eCommerce provides Authorization Server to clients to request and obtain the Access Token. The Access Token is used to access data from the DHL eCommerce business Global APIs (e.g. Fulfillment API, Label API). This page provides basic guidelines and examples of authentication workflow to demonstrate how to use the Access Token API.



OAuth


1) Obtain client id and client secret

To obtain the credentials please contact DHL eCommerce Representative via Contact. You will recieve a different credentials for Sandbox and Production environment.


2) Obtain Access Token

To obtain the access token from the Authorization Server you have to submit client_id and client_secret using HTTP Basic authentication, where username is represented by client_id value and password is represented by client_secret value.

The Access Token authorizes you for an access to the Fulfillment API. Each obtained token is valid for certain amount of time (default is 5 hours), therefore you do not have to obtain token for each API resource request, but you can use the same token until it expires. To test the Access Token API you can put the following URL to the browser and use client_id and client_secret as a username and password to get you Access Token.

Note: There are two Authentication APIs available to generate access token. Prefered option is the Authentication API for Global APIs (including Fulfillment). The Authentication API just for Fulfillment is still available, but deprecated.

Sandbox Authentication API for GAPI APIs: https://api-qa.dhlecommerce.com/account/v1/auth/accesstoken
Sandbox Authentication API for Fulfillment API: https://api-qa.dhlecommerce.com/efulfillment/v1/auth/accesstoken

Production GAPI APIs: https://api.dhlecommerce.com/account/v1/auth/accesstoken
Production Fulfillment API: https://api.dhlecommerce.com/efulfillment/v1/auth/accesstoken


OAuth

This is the successful response which you will see in the browser. The response has to be processed by your client application, where the application logic extracts the access token from the access_token parameter and include it in any subsequent request for the Fulfillment APIs.


HTTP Response Status Code 200
{
  "access_token": "K3gUwpA1DdSdGWZxeaJ......................",
  "token_type": "Bearer",
  "expires_in": 18000,
  "scope": "efulfillment"
}
                

This is the failed response which you will see in the browser in case of invalid credentials.


HTTP Response Status Code 401 Unauthorized
{
  "error" : "invalid_client",
  "error_description" : "Client authentication failed (e.g. unknown client, no client authentication included, or unsupported authentication method).
  The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. "
}