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.
Key | Value |
---|---|
client_id | 07E965CC-2425-44C6-88D8-9A694C30CCAA |
client_secret | PelLobiJuumPwCUMDalM0AD0bzCDDciEMqFv6Bno |
dealtrack_registration_id | 688B42F8-60C8-4556-9912-0CD5E69C83D7 |
scope | read:deals read:activity |
grant_type | client_credentials |
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}
.
Comments
0 comments
Please sign in to leave a comment.