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

A JWT can be generated by passing access credentials to an endpoint at oauth2/token. The token endpoint requires the API consumer to post the following as application/x-www-form-urlencoded form data:

• client_id
• client_secret
• dealtrack_registration_id
• scope
• grant_type

client_id, dealtrack_registration_id

The dealtrack_registration_id and client_id are Universal Unique Identifiers which will be provided to you when Enable provides you access to the API. They are used to uniquely identify you and your DealTrack client instance.

client_secret

The client_secret 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 client_secret is a password it must be stored securely and only shared with trusted parties.

scope

The JWT can be used to give selective access to different parts of the DealTrack API. This is achieved with token scope. When requesting a new token from the API you must include the scope that you require access to. If your credentials permit access to those areas of the system, then a token will be returned that can grant access to the endpoints that return data from that part of the system. However, if the requested scope encompasses an area of the system that you do not have permission to access, then an error of invalid_scope will be returned.

There are currently three supported values that can be contained within the scope field. They provide read access to deals, activity logs and users respectively.

• read:deals
• read:activity
• read:users

If you want to request data from the Deals endpoint, for example, then read:deals must be included in the scope field. If you do not include this, then you will not be able to access the Deals endpoint.

The value of the scope field is expressed as a list of space-delimited, case-sensitive strings. You can increase the scope of the token by appending items, such as read:deals, to this list.

grant_type

The grant_type is the flow that the API uses when authorizing a token request. It dictates the process used when you attempt to gain access to the API.

Currently, the API only supports the Client Credentials flow and therefore, the grant_type field should always be set to client_credentials.

Example

An example has been provided below for how to request an authentication token. The following form data is included within the example.

curl --requestPOST "https://api.deal-track.com/oauth2/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "client_id=07E965CC-2425-44C6-88D8-9A694C30CCAA" --data-urlencode "client_secret=PelLobiJuumPwCUMDalM0AD0bzCDDciEMqFv6Bno" --data-urlencode "dealtrack_registration_id=688B42F8-60C8-4556-9912-0CD5E69C83D7" --data-urlencode "scope=read:deals read:activity" --data-urlencode "grant_type=client_credentials"

Token Authentication Response

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

{
    "access_token": "{token_string}",
    "expires_in": {time_in_seconds},
    "token_type": "Bearer"
}

The token_string is the string you will need to pass to the DealTrack API as the bearer token value for any subsequent requests. The expires_in 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.

If the API is unable to process the authentication request, then it will return the following response:

{
    "error": "{error}"
}

Where error will be one of the following:

• invalid_request
• invalid_client
• invalid_scope
• unsupported_grant_type

Using the JWT

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