The DHL Authentication API allows to generate access tokens for DHL Group APIs which use this service as their authentication provider.

• What: Generate access tokens, either JWT or Opaque.
• Who: for those APIs from DHL Group which explicitly use this service for authentication. Please read the documentation from the API you are trying to access.
• How: API Userguide.
• When: Obtain an access token from this API prior to consuming the API you are trying to use.

Scope

The API shall be used to generate a time-limited token which can then be used to consume other APIs.

Using the API

2 formats are supported:

• Opaque tokens: A proprietary format that usually contain some identifier to information in a server's persistent storage. Needs a validation server to work properly.
• JSON Web Token (JWT): Follows the JSON Web Token (JWT) standards and contain information pertaining to an entity given in the form of claims. They are self-contained, thus not requiring a call to a validation server.

Example Use Case

Retrieving a JWT token

DHL Authentication API is a companion API that offers authentication services for other DHL APIs. In effect, any requested app will be given a consumer key (client_id) and a consumer secret (secret_key) which can be used to call this API with Basic Authentication, to generate an access token to consume another API.

Refer to User Guide for a detailed instructions.

Using the Authentication API

Get Access

DHL Authentication API is a companion API. Access to this API will be given automatically when you are given access to a different API which uses the Authentication API for authentication services.

AUTHENTICATION

Every call to an API requires a subscription key. To call the Authentication API, the same key as your approved app will be used.

To view your API subscription keys:

• From the My Apps screen, click on the name of your app.
• The app details page will be shown.
• Here you can find:
• Consumer Key = client-id
• Consumer Secret = secret-key
• Click the Show link below the asterisks to show both values.

Get a token

To get a token, this API accepts a POST request with Basic Authentication in which the client-id and secret-key will be sent base64 encoded in the authorization header as follows:

authorization: Basic <base64-encoded-key>

• base64 encoded key: this is the base64 encoded of <client-id>:<secret-key>

Example of how to base64 encode a key in linux

$ echo <client-id>:<secret-key> | base64

CURL example to generate an opaque bearer access token

curl -X POST "https://api-sandbox.dhl.com/auth/v1/token?response_type=access_token&grant_type=client_credentials" -H "accept: application/json" -H "authorization: Basic <your-basic-base64-key>"'

Response received should be similar to below:

{
    "access_token": "aVX6xgQSanylwsnVwaANfp8nIC2U",
    "id_token": "",
    "scope": "",
    "token_type": "Bearer",
    "expires_in": 1692
}

CURL example to generate a JWT token

curl -X POST "https://api-sandbox.dhl.com/auth/v1/token?response_type=id_token&grant_type=client_credentials" -H "accept: application/json" -H "authorization: <your-basic-base64-key>"'

Response received should be similar to below:

{
    "access_token": "xfYGzG43bZMIaq5RNyPXgi2KgPqK",
    "id_token": "eyJraWQiOiJlODIzMDhhNC1iOTFlLTEwMDgtNDZkMS0zNDQ3NjY5NmI2OTUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhcHAiOiJBcHBzIGZvciBmZWF0dXJlIGJyYW5jaCB0ZXN0aW5nIiwiYW1wLWNsaWVudGlkIjoiYW1oVWRjZEdwZzVQVG54d3UyVjJ2Q3hRZlRWSGhZWXoiLCJzdWIiOiJkYXJyZW4uY2hvbmdAZGhsLmNvbSIsImF1ZCI6IkRITCIsInByZCI6IlByb2R1Y3QgZm9yIGZlYXR1cmUgYnJhbmNoIHRlc3RpbmciLCJhbXAtYXBwIjoiQXBwcyBmb3IgZmVhdHVyZSBicmFuY2ggdGVzdGluZyIsImFtcC1lbWFpbCI6ImRhcnJlbi5jaG9uZ0BkaGwuY29tIiwiaXNzIjoiZHBkaGwtbm9ucHJvZC1kZXYtZ2ewaS5hcGlnZWUubmV0IiwiZXhwIjoxNTc5NzY2MDU1LCJpYXQiOjE1Nzk3NjU5MzUsImp0aSI6IjZlMDkzZjZiLWJhOWMtNDllMS1iOGJkLTgxZjJkNmZiODFmZCIsImNpZCI6ImFtaFVkY2RHcGc1UFRueHd1MlYydkN4UWZUVkhoWVl6In0.qhSvyz7laJ4KhjiJALAdqRcASvBp8g9cBwuzPDZGwVFs1dEeL_pqqHFwfShbP6l03UJYjEwQ7irCYmRgZfw8B9iPak-DvB8CzoStTj2ANd17kyuvsOtnPymLwDgSHzFD9MSp4gFl-h_pzca0lUF2Fmo8qnDQGxl6ojWBONxi86fY-XOLVCN4hAVg2JpgjzXXJbrctePLBwfLP3qVfoAVds3d171WRKYnPRggYllHae9e14uJmByZCzAHDnDCuHHeHDmSFvis67Ek5M0BoBdwcoFB_g8XJooSzFIgZP8tanBFAzYcA9wg5EHvFjbs_Lw4M6uyQvhlajTdYoGIK68YEw",
    "scope": "",
    "token_type": "Bearer",
    "expires_in": 1734
}

Environments

The addressable API base URL/URI environments are: