Authentication Tutorial

Here’s what you need to know to authenticate with the Daxko API!

Get API Access

If you haven’t already been granted access to the Daxko Operations API, you should contact your sales representative and request access. Once this step has been done, you should have a username, password and refresh token for your API account. You will need this information to authenticate to the API.

Authentication Workflow

The authentication workflow comprises of two steps:

1. Use your refresh token to get a client-scoped access token
2. Use the client-scoped access token to access resources

For each step, the Authorization header must be present.

Get client-scoped access token

So you’ve been granted access to the Daxko API! Let’s pretend you were given the following credential information for illustration purposes.

The refresh_token can only be used for the /v3/partners/oauth2/token endpoint. In order to access other endpoints in the Daxko API, you will have to use the access token returned from the /v3/partners/oauth2/token endpoint in place of the refresh_token.

What you will do is use the refresh_token to generate an access_token that is scoped to a particular Daxko Client, e.g., client with ID 9999. This access_token will be used for other API resources and will restrict the data return from the API to only data for the particular Daxko client. In order to get this access token we need to request it from the /v3/partners/oauth2/token API endpoint.

The /v3/partners/oauth2/token endpoint is an OAuth 2 endpoint that supports the client_credentials flow, and because of that, the parameter names for the endpoint are not named the same as your credentials. Use the following mapping to determine what values to use for the input parameters.

An example curl request would be

curl -XPOST {base_url}/v3/partners/oauth2/token \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-F "grant_type=client_credentials" \
-F "client_id=daxko_api_user" \
-F "client_secret=d9a2652cf96d734661c10d5ff2f8061f" \
-F "scope=client:9999"

To make an API request to the /v3/partners/oauth2/token endpoint, the refresh_token must be present in the Authorization header, and have the format Authorization: Bearer <refresh_token>

The response body will return an access_token that is scoped to the client you specified with the scope body parameter, along with an expiration time in seconds indicating how long the token is valid. An example response would be

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": "86400",
  "token_type": "bearer"
}

The access_token will replace the refresh_token in the Authorization header for requests to API resources other than the /v3/partners/oauth2/token endpoint.

This access_token will be valid the time elapses as specified in the expires_in response parameter, at which point you will need to request a new access_token by following the same steps above. The Daxko API will respond with a HTTP 401 status when the expiration_timestamp has elapsed. Your application should watch for this response, and request a new access_token when that response is returned.sl

Access API resource

Now that you have a time-limited, client-scoped access token, you are able to access any endpoint. The only authentication requirement is that the Authorization header be present and have the format

Authorization: Bearer <access_token>

Note, this is the access_token value returned from the /v3/partners/oauth2/token endpoint, NOT the refresh_token provided to you as part of your API account credentials.

Now, you are able to access other resources, such as the /v3/members/oauth2/token resource, for example, with the following curl request

curl -XPOST {base_url}/v3/members/oauth2/token \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc..." \
-d '
{
  "username": "member_name",
  "password": "member_password",
  "grant_type": "password",
  "scope": "member:auto_login"
}'

Securing your access token: The access_token should always be secured on your server and not be sent to a web browser or mobile device. If an attacker gains access to your access_token, then the attacker would have full access to every API call documented on this site.

Comments