Access & Authentication

How to get access to our delivery API

Many endpoints in the delivery API supports both anonymous and authenticated requests. If a user is authenticated permissions and personalisation will take affect on a given endpoint changing returned data like prices, what content is available, discounts, assortments and other user dependent information.

Some endpoints always require authentication, e.g. endpoints related to users, order histories, and favorites.

Authentication

Authentication works through authenticating with a username and password. This returns a JWT containing the necessary information to identify the user and the validity of the token.

To authenticate a user and obtain a JWT, use the authenticate endpoint.

Using GET:

GET <yourHost>/dwapi/users/authenticate?userName=DemoUser&password=TestPassword123

Using POST:

POST <yourHost>/dwapi/users/authenticate
{
  "username": "DemoUser",
  "password": "TestPassword123"
}

Response would look like the following:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIxMyIsIm5iZiI6MTY4NDgyMTQ1MywiZXhwIjoxNjg0ODIyMDUzLCJpYXQiOjE2ODQ4MjE0NTMsImlzcyI6IkR5bmFtaWN3ZWIgQS9TIiwiYXVkIjoiV2ViQVBJIn0.E6qnfrmb2adq3SvFpyatjXsy78xf2SZxuVhCr1EJTXQ"
}

This token has to be stored in the client (your app) and then subsequently used in most of the other endpoints where authentication is required to handle on a specific user or with specific permissions or personalization.

The returned JWT has to be used as a header authorization bearer token:

authorization: Bearer <token>

where <token> is the value returned in the authenticate response, e.g.:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIxMyIsIm5iZiI6MTcxMzg4ODk5OCwiZXhwIjoxNzEzOTc1Mzk4LCJpYXQiOjE3MTM4ODg5OTgsImlzcyI6IkR5bmFtaWN3ZWIgQS9TIiwiYXVkIjoiV2ViQVBJIn0.Q1xPxgNqp9ahjexB0nl7xz5iv52q22mTOljj5va1a5U

JWTs are valid for a specific time. Default expiration for JWT in DynamicWeb is 1800 seconds, which is 30 minutes. This can be made shorter or longer when calling the authenticate endpoint. Longer expiration times are more insecure.

Before the token expires, it has to be refreshed, so your app should keep track of when the token was created so it can be refreshed before it expires. If a refresh is not made before the timeout, the login expires and the user has to authenticate again.

Refreshing JWT token

Refreshing the token is done using the refresh endpoint and passing in the Bearer token as well:

authorization: Bearer <token>

GET <yourHost>/dwapi/users/authenticate/refresh?expirationInSeconds=600

Which will provide a new token with a new expiration.

Impersonation

Impersonating lets you act in the role as another specific user, as long as you have the proper permissions to do so. You will simply be granted another token to use, which will have the identity of the user that's being impersonated.

To list all the users that's allowed to be impersonated with the given JWT token in the request, use

GET <yourHost>/dwapi/users/impersonatees

Including a header such as

authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIxMyIsIm5iZiI6MTY4NDgyMTQ1MywiZXhwIjoxNjg0ODIyMDUzLCJpYXQiOjE2ODQ4MjE0NTMsImlzcyI6IkR5bmFtaWN3ZWIgQS9TIiwiYXVkIjoiV2ViQVBJIn0.E6qnfrmb2adq3SvFpyatjXsy78xf2SZxuVhCr1EJTXQ

The response is a list of users that can be impersonated

[
  {
    "address": "Vejnavn 1",
    "city": "Aalborg",
    "company": "Company Customer DK",
    "country": "Denmark",
    "countryCode": "DK",
    "email": "noreply@dynamicweb.dk",
    "id": 87,
    "name": "Company Customer DK",
    "phone": "87654321",
    "userName": "CompanyCustomerDK",
    "zip": "9000",
  },
  {
    "email": "noreply@dynamicweb.dk",
    "id": 88,
    "name": "Company Customer UK",
    "userName": "CompanyCustomerUK",
  }
]

Impersonating one of these users is now as simple as calling GET <yourHost>/dwapi/users/impersonate?userId=87 With the authorization header as the previous request.

The response will the contain a new token for the specified user

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI4NyIsIm5iZiI6MTY4NDgyMzA0MCwiZXhwIjoxNjg0ODIzNjQwLCJpYXQiOjE2ODQ4MjMwNDAsImlzcyI6IkR5bmFtaWN3ZWIgQS9TIiwiYXVkIjoiV2ViQVBJIn0.SpwDL7pq2LjcXSoZiaZ3hqdT3nU3X0JE4ZIBzBPlEnA"
}