1 Authentication and Authorization

1.1 Intro

The DHL API endpoints (but not all) make use of JWT (JSON Web Tokens) for secure authentication and authorization. DHL secure endpoints are identified by a lock in the API docs (see right hand side of the specific endpoint).

The JWT token is necessary to test and work in the DHL production environment when dealing with secured endpoints. This token is to be provided in the Authorization header of the HTTP request using the ‘Bearer’ scheme.

DHL has chosen JWT not just for authentication but also for the secure exchange of JSON information pertaining to the user account.

Precondition

A business account for My DHL Portal.

A business account is handed out by the sales department. You can place a request for an account as a business by email to: CIM eCommerce BNL.

1.2 Services

1.2.1 Get your user-id and key

To get an authentication token, you will need the user-id and user key for your application. These unique values can be generated under the user account on the My DHL Portal application page.

By selecting ‘Settings’ in the user dropdown menu and clicking the button ‘CREATE API KEY’ in the tab ‘API KEYS’, the user-id and key are generated. Hold on to this information, since it will only be given out once. When pressing the button again, a new user-id and key will be generated, overwriting and invalidating the previous one.

My DHL Portal API Keys

1.2.2 Get your authorization token

The user-id and key are used to make the initial call to the Authenticate API key endpoint. As a response, the endpoint returns both an access token and a refresh token.

The access token is valid for a limited time, indicated by the expiration time in the response attribute ‘accessTokenExpiration’. When this time (expressed as a unix time stamp) has expired, the secure access can again be established by obtaining a new access token using the refresh token and the Authenticate refresh token endpoint. Please keep in mind that this refresh token also has an expiration date time, but it is significantly longer than that of the access token.

The response of the refresh endpoint is the same as the initial call to the Authenticate API key endpoint; it also results in an access and a refresh token with expiration date times.

The resulting access tokens contain some encoded information about your access rights, including a list of account numbers. By default, access tokens give access to all account numbers assigned to your API key user. To limit this list, you may provide the optional accountNumbers field in your authentication request.

Example of response body (200) of the /api-key:

{
  "accessToken":"yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwOGZkMTRhMC05YWYzLTRkZDMtODU3YS1hNzUyYWY3ZjUyYTciLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDMyNDMxNSwiZXhwIjoxNTEwMzI1MjE2LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.D9Zf0hnDXhPXoWar42wzSiZHRKLBYriyKQyj1zERrBw",
  "accessTokenExpiration": 1510325216 ,
  "refreshToken":
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhMWQ5MDMyMi04YmRiLTQ1NjQtOTMxMy04OTg5N
ThmMzgwNDQiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRp
b25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDMyNDMxNSwiZXh
wIjoxNTEwOTI5MTE2LCJyb2xlcyI6WyJhdXRoLXNlcnZpY2UuUkVGUkVTSCJdLCJhY2NvdW50cyI6WyIwODUwMD
AwMSJdfQ.fi7hn6u3mFwcJ4AG8cYEh8OJFm2NDwOt407aP7sENSo",
  "refreshTokenExpiration": 1510929116,
  "accountNumbers": ["1234567"]
}

The accessToken to be used in the HTTP header for authentication. The accessTokenExpiration is the unix time stamp for the expiration of the token (in this case, 2017-11-10 14:46:56Z).

The refreshToken may be used to obtain a new accessToken without having to re-supply credentials. It has a longer expiration (refreshTokenExpiration) than the access token. This makes it possible to set up a longer-running session without the need to store original credentials.

The accountNumbers field lists all account numbers that the access token grants permission to use.

1.3 API Usage

Description	URL
API to get your tokens	https://api-gw.dhlparcel.nl/authenticate/api-key
API to be used with the refresh token	https://api-gw.dhlparcel.nl/authenticate/refresh-token

1.3.1 Get access token

Request examples

Curl

curl -X POST "https://api-gw.dhlparcel.nl/authenticate/api-key" -H "Accept:application/json" -H "Content-Type: application/json" -d "{\"userId\": \"f36abdfa- 9894-4d1f-bb6e-e471a953c04d\", \"key\": \"1c8545e1-767f-4531-9c6b-5f5f80737562\"}"

PHP

<?php
$auth_string = '{"userId":"{userID}","key":"{key}"}';
$ch = curl_init('https://api-gw.dhlparcel.nl/authenticate/api-key');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $auth_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Accept:
application/json'));
$auth_response = curl_exec($ch);
$api_key = json_decode($auth_response);
$accessToken = $api_key->{'accessToken'};
?>

Responses

Success (code 200)

{
  "accessToken": "_Your token_",
  "accessTokenExpiration": 1510138597,
  "refreshToken": "_Your refresh token _",
  "refreshTokenExpiration": 1510742497,
  "accountNumbers": ["1234567"]
}

1.3.2 Refresh token

Request examples

Curl

curl -X POST "https://api-gw.dhlparcel.nl/authenticate/refresh-token" -H "Accept:application/json" -H "Content-Type: application/json" -d "{\"refreshToken\":\"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwMWVlYjBkMy1hZmM0LTRiYjEtYTgzZS0wZDkxYzE4ZjVhZDUiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDIxMDcxNSwiZXhwIjoxNTEwODE1NTE2LCJyb2xlcyI6WyJhdXRoLXNlcnZpY2UuUkVGUkVTSCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.y-Hm3T6_moUWXF_v2uyOXcX7tu1uddyhG6fsDQliPXw\"}"

Responses

Success (code 200)

{
  "accessToken": "_Your token_",
  "accessTokenExpiration": 1510138597,
  "refreshToken": "_Your refresh token _",
  "refreshTokenExpiration": 1510742497,
  "accountNumbers": ["1234567"]
}

1.4 Testing

These test cases with their positive outcomes are merely suggestions and it is not an extensive test set, e.g. tests with a negative outcome should also be taken into scope. Please extend with test cases which are suitable for your line of business or wishes.

Suggested Test Cases	Expected Result
Create an authorization token (initial request)	An access token and a refresh token with expiration are returned by the My DHL Portal application.
Create an new authorization with refresh token	An access token and a refresh token with expiration are returned by the My DHL Portal application.