Requesting Access Tokens

This page describes how to use the Authentication API to request an access token, which must be used in the authentication header of all other calls to the zDirect API.

Securing your Credentials

Caution

The client ID and client secret are used to protect your account from unauthorized access. They should be treated as highly confidential.

  • Never share your credentials in an insecure medium such as email or chats.
  • Never store your credentials locally or in your code repository in unencrypted files.

Client ID and Client Secret

Every app created and managed by the zDirect Portal is automatically assigned a client ID and a client secret. To get the client ID and client secret:

  1. Log into the Applications section of the zDirect Portal.
  2. Select the appropriate app.
  3. Scroll down to "Credentials" to find the client ID and client secret.

For more information, see Creating and Managing Apps

Call the Authentication API to Request Access Token

Use the /auth/token endpoint to request an access token.

Pass the $CLIENT_ID and $CLIENT_SECRET, use the grant_type parameter to request client_credentials, set the Content-Type header to application/x-www-form-urlencoded and provide the scope access_token_only (to make sure we will not issue a refresh token) as shown in this sample httpie command:

http \
-a $CLIENT_ID:$CLIENT_SECRET \
--form POST \
https://api-sandbox.merchants.zalando.com\
/auth/token \
Content-Type=application/x-www-form-urlencoded \
grant_type=client_credentials \
scope=access_token_only

The actual HTTP request looks like this:

POST /auth/token HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Basic
MzjbR3w2fXtEwZ6byr694RZ27xVWe4odH1cm55f6UeO62wCdQAKTYECMwhoRJLduAfydsduov9Mfavz9q4MzI4Fpk909
Connection: keep-alive
Content-Length: 29
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: api-sandbox.merchants.zalando.com

grant_type=client_credentials&scope=access_token_only

Note

From 1st July 2021, the scope access_token_only will not be required anymore to issue only access tokens as this will become the default behavior for every authentication request. If you are already passing the access_token_only scope for your authentication requests, your integration will continue to work unaffected.

Basic Authorization Header

httpie encodes client ID and client secret as a Basic Authorization header. Many libraries include methods to do this, but if you wish to build the header yourself, follow these steps:

  1. Concatenate the $CLIENT_ID and the $CLIENT_SECRET, separated by a :
  2. Encode the result as a base64 string.

Response

If successful, you will get an HTTP 200 response similar to the example below. The long string beginning with eyJh is the access token. Note that the reply also does not include a refresh token.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 3054
Content-Type: application/json
Date: Tue, 30 Oct 2018 12:46:30 GMT

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxSXJSLUZkdm5vcms2RktjcV9nNDFUa3p4VC16dk8welRyUHFUM0tMem9zIn0.eyJqdGkiOiI4MzFkZDQ5My1kY2UxLTRjNDMtYTQxMC1kMmZiNmU4ZDY4ZGUiLCJleHAiOjE1NDA5MTA3OTAsIm5iZiI6MCwiaWF0IjoxNTQwOTAzNTkwLCJpc3MiOiJodHRwczovL21lcmNoYW50LWlhbS5kZWZhdWx0LnN2Yy5jbHVzdGVyLmxvY2FsL2F1dGgvcmVhbG1zL21lcmNoYW50LXBsYXRmb3JtIiwiYXVkIjoidGVzdC1ub24taW50ZXJhY3RpdmUiLCJzdWIiOiIwN2I1M2VkYy02Mjc4LTQ3NjQtODA0MS1jYzNiYjBjZWI5MmQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ0ZXN0LW5vbi1pbnRlcmFjdGl2ZSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjljNjIyYWExLTU0ZGYtNGRkNC04ZGFjLTQyMWVjODBhZjIwMyIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZXNvdXJjZV9hY2Nlc3MiOnsidGVzdC1ub24taW50ZXJhY3RpdmUiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sInRlc3QtcmVzb3VyY2UiOnsicm9sZXMiOlsicmVhZCIsIndyaXRlIl19LCJ6ZnMiOnsicm9sZXMiOlsiaXRlbS1xdWFudGl0aWVzL3JlYWQiXX0sIm9yZGVycyI6eyJyb2xlcyI6WyJyZWFkIiwid3JpdGUiXX0sImFydGljbGVzIjp7InJvbGVzIjpbImVhbi9yZWFkIiwic3RvY2svcmVhZCIsInN0b2NrL3dyaXRlIiwicHJpY2Uvd3JpdGUiXX19LCJzY29wZSI6IiIsImNsaWVudElkIjoidGVzdC1ub24taW50ZXJhY3RpdmUiLCJicGlkcyI6IjE5ZTNiZGMwLTQ0MDItNGMzNC04OWE2LWI3OTgyNDQyMDc5MSwxNjcwYTc5OC04MzUyLTQwNWYtOWE4Yy05MTJjNjU4ODE5NmIsMDAwMDAwMDAtMDAwMC0xMDAwLWEwMDAtMDAwMDAwMDAwMDAxIn0.jZ4tM3gTgSJh1XVb8sZvzLmNFATSM7lKOjYgQtm9IXVCVwRFDr7YJc4tfvnYAmmqAYgClPtIiWnKfEykfApv_CuNXqEBsw88gL-ROw9cfK5fKuRLXmNVOLb4Iy1Qrvm4Rk2t1Pem5HClM3Zw345INlNrNPQPlaRMioyw9ORmW0K-a90CLPiGnZo1Qb6F2n7zpOSTuF-p-6kaqLQs8ixFkFqRaoj3pyt5OkOlgnZ0a_8T8F8ZohBak6iLkyJaAHAE_aKLVq3GmM_Pis4ieCts33QdRR0pWg0drrdGUDXtgGYaDebULaHP0niZb0yNd0Fl3F8HCpuVNfdMtFaIvqW-OA",
    "expires_in": 7200,
    "not-before-policy": 0,
    "scope": "access_token_only",
    "session_state": "9c622aa1-54df-4dd4-8dac-421ec80af203",
    "token_type": "bearer"
}
Contact Support