Authentication

Authentication Type

Bearer token authentication is used to ensure only relevant DealTrack customers can access and read information from the DealTrack API. In order to retrieve data back from any DealTrack API endpoint, a valid JSON Web Token (JWT) must be passed on every request.

Generating a JWT Token

This JSON Web Token (JWT) can be generated by passing access credentials to an endpoint at oauth2/token. The token endpoint expects the user to post the following as form data:

• ClientId
• ClientSecret
• Scopes
• RegistrationId

ClientId, RegistrationId

The RegistrationId and ClientId are Universal Unique Identifiers which will be provided to you when Enable provision the API for you. They are used to uniquely identify you and your DealTrack client instance.

ClientSecret

The ClientSecret is the password you provide to the API to verify your identity, this will be provided to you securely when Enable provision the API for you. Since the ClientSecret is a password it must be stored securely and only shared with trusted parties.

Scopes

The bearer tokens can be used to give selective access to different parts of the DealTrack API. This is achieved with Scopes. When requesting a new token from the API you include the scopes you require access to. If your credentials permit access to those areas of the system, a token will be returned that can grant access to the endpoints that return data from that part of the system.

For example, there is a read:deals scope which allows users to request data from the Deals endpoint amongst others. If you do not have the read:deals scope, you will not be able to access the Deals endpoint.

Multiple scopes can be requested for a single token. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. This is an example of how to do that from a REST client:

Token Authentication Response

If a token is requested using valid credentials you will receive a response in the following structure:

{
    "accessToken": "[token string]",
    "expiresIn": [time in seconds]
}

The “accessToken” is the string you will need to pass to the DealTrack API as the Bearer Token value for any subsequent requests. The “expiresIn” value is the time left in seconds until the token expires. After this time the token will stop working and it will be necessary to request a new one.

Using the JWT Token

Once requested, the token can be stored locally and used until expiry. For every request, the DealTrack API endpoints require users to set the Authorization mode to “Bearer” and set the value to the accessToken. This can be done by adding a Header named “Authorization” with a value of Bearer {bearer-token-string}