last updated May 31 2023

The Parcel DE Authentication API allows you to obtain a token to access a number of Parcel Germany APIs.

This API offers a single resource /token and a testing resource /hello where you can try out token-related functionality before you use it with APIs such as Parcel DE Returns or Parcel DE Account.

Making your first call

Refer to the technical description (OAS / Swagger) for details on endpoints, operations, parameters, formats.

Refer to the information in the user guide for more textual information.

Technical Overview

The Authentication API is a shared functionality used by multiple APIs. It is used to obtain an access token for API access. In itself, it does not provide any business functionality but supports multiple APIs of Post & Parcel Germany.

The API provides an implementation of an OAuth2.0 resource-owner password credentials flow. Tokens can be used for all P&P APIs supporting the Authentication method. For a list of APIs, see below.

Get Access

Please follow the instructions on the documentation pages of the business API you want to use. The credentials (client_id and client_secret) you have obtained there will allow you to use this functionality as well. You do not need extra credentials for the Authentication API.

Obtaining a token

The following curl command illustrates how to obtain a token.

curl -k -i -X POST-H "accept: application/json" -H 'content-type: application/x-www-form-urlencoded' https://api-sandbox.dhl.com/parcel/de/account/auth/ropc/v1/token -d "grant_type=password\&username=max.mustermann\&password=MeinPasswort123#\&client_id=lr8wTCJjcNnNL9HVYxQYTO6NGqlcGIGg\&client_secret=hz0ofecvbAaEJxWF"

Environments

The following table outlines key differences between environments.

Testing the API

You can:

• try out the API directly here against the sandbox environment (client_id and client_secret needed as well as predefined backend user and password)
• use the postman collection provided (client_id and client_secret needed)
• adjust the curl example

The /hello endpoint allows testing with the fresh token you have obtained.

APIs supporting token based authentication

General Questions

I want to use a certain API and followed a link to this API. What gives?

This API (Parcel DE Authentication) provides functionality to obtain an OAuth access token. With that token, you can call several Parcel APIs.

My setup works for getVersion() but I get HTTP 401 for all other calls.

getVersion is a call to the basepath of the API (e.g. https://api-eu.dhl.com/parcel/de/account/auth/ropc/v1/). This call can even be made from a browser and does not require credentials.

I requested access and did not hear back for 48 hours or more.

Apologies. Please reach out via contact form. Approval to production is not automatic.

Go-Live

Will I use the same key for PROD and SANDBOX?

If you have requested access to both sandbox and production products in the same app, the same key will be typically be enabled for both PROD and SANDBOX. We can set you up based on your preferences. We can also add PROD access if you had originally only requested sandbox access.

Token

What kind of token is that?

We provide an opaque access token (example: JU8VQkQaBHnKsphAuGQPKF1VAoBv) to be used as Bearer token in the Header Authorization.

Do I need anything beyond the access token?

No. For business calls you provide simply the access token in the HTTP header. There is no additional credential needed.

Where can I find more information?

The implementation follows https://www.rfc-editor.org/rfc/rfc6749, please refer to the RFC for more detail.

Token expiration

The access token does expire after a relatively short time (e.g., 5 mins). After expiration, you have to request a new token. Please refer to the OAS for details.

Testing

How should I test the hello endpoint?

The hello endpoint supports both token based as well as traditional (key + user + password) authentication. It is meant as help during development.