Authentication

A word on tokens

There are two types of tokens that our API uses. The first type is an access token, which is a short-lived token (1 hour) that you will use on every API request.

The second type is a refresh token, which, along with an expired access token, allows you generate a new access token. A refresh token has a longer expiration limit (2 weeks).

Authenticating against our APIs

Access to all API endpoints will require authentication using JWT (JSON Web Tokens), which you will be able to obtain from our authentication service. Once you obtain your initial access token, you will be able to exchange it for a new access token (as long as your account is active) using the provided refresh token.

The authentication endpoint

The authentication endpoint will be available at https://api.partners.daxko.com/auth/token. You can also refer to the API reference page for information about the endpoint.

Getting a new set of JWT credentials

In order to retrieve a new access token, you will need to make a POST request to https://api.partners.daxko.com/auth/token with the following JSON payload:

key	value
`client_id`	This will be the username you were provided when your API credentials were generated.
`client_secret`	This will be the password you were provided when your API credentials were generated. Your password should be securely stored and should only be required when you first generate your access token.
`scope`	This is the ID for the customer/client you are trying to programmatically interact with. Note that, while you may have access to multiple clients in your account, you will need to generate a new token for each client you are accessing.
`grant_type`	This will always be set to `client_credentials` when getting a new token.

You can replace the values below and test an authentication request from the command line as follows:

curl -X POST \
  https://api.partners.daxko.com/auth/token
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_PASSWORD>",
    "scope": "<THE_CLIENT_YOU_ARE_TRYING_TO_ACCESS>",
    "grant_type": "client_credentials"
  }'

If authentication is unsuccessful, you will receive a 401 status-code response. Otherwise, you will receive a 200 status-code response with your token and refresh token.

Response payload

The response payload will look like the following:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkZXYtYXBpLnBhcnRuZXJzLmRheGtvLXFhLmNvbSIsImF1ZCI6W10sImNsaWVudHMiOlt7ImNsaWVudElkIjoiQ0FfMTIzNDUiLCJ1c2FnZUtleSI6IjFjYjA4ZmUzLTIyZDgtNGM4Yy1hYjNiLTJmMmM0M2EzZTg0NCJ9XSwiaWF0IjoxNTUxMTA3NTIxLCJleHAiOjE1NTExOTM5MjEsInNjb3BlcyI6WyJncm91cGV4OioiXSwic3ViIjoiZG9jcy10ZXN0ZXIifQ.m4__j0zqYGniulL6Da-2RVOSn5rQ_TsoIZHEhUhXjZA",
  "expires_in": 86400,
  "token_type": "bearer",
  "refresh_token": "a82c85794acbf26427186c7d8d516c09f9afe160"
}

Key	Description
`access_token`	This is the short-lived token you will need to use in your `Authorization` header while making any subsequent requests to any API endpoints. It must always be preceded by `Bearer`. Therefore, an example will be `Authorization: Bearer eyJhbGciOiJIUzI1NiIs...`
`expires_in`	The duration for which the token is valid for, in seconds.
`token_type`	This will always return `bearer`
`refresh_token`	The token you can use to exchange an expiring or expired access token for a new one, without the need to provide your password again.

{
  "client_id": "docs-tester",
  "refresh_token": "a82c85794acbf26427186c7d8d516c09f9afe160",
  "grant_type": "refresh_token"
}

Refreshing your authentication token

Once you have authenticated for the first time, you will be able to obtain a new token by simply providing your username and your previously obtained refresh token instead of your password.

Note: You should still treat your access token as you would any other password and take extra precautions to store it securely.

In order to refresh your existing token, you will need to make a POST request to https://api.partners.daxko.com/auth/token with the following JSON payload:

key	value
`client_id`	This will be the username you were provided when your API credentials were generated.
`refresh_token`	The refresh token you obtained when you first obtained your access token.
`grant_type`	This will always be set to `refresh_token` when refreshing your token.

You can replace the values below and test out an authentication request from the command line as follows:

curl -X POST \
  https://api.partners.daxko.com/auth/token
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<YOUR_CLIENT_ID>",
    "refresh_token": "<YOUR_REFRESH_TOKEN>",
    "grant_type": "refresh_token"
  }'

As with the authentication request, the response will be a 401 if authentication is unsuccessful, and 200 if the response is valid. The payload will be the same as that of an authentication request.

Scope of your refreshed token

Please note that, any time you refresh your token, a new token will be issued with access to the client the original token was issued for. If your credentials have been revoked or API access to that customer has been removed between original token issuance and the refresh request, you will not be able to successfully refresh your token.