CDP uses a query string authentication scheme. All calls made to the CDP webtag APIs contain information to authenticate their source.
The authentication process has the following steps:
Examples of these steps are provided using Postman, a REST API client or cURL, a command line tool. However, you can use any client or library to test and implement the API calls in your environments.
Before you can integrate with CDP’s DW Tracker API, your Implementation Consultant (IC) must provide you with:
Examples of the token management subdomain:
| Region | Pre-Production Environment | Production Environment |
|---|---|---|
| US AWS | cs-auth | auth |
| EU AWS | cs-auth.eu | auth.eu |
| US GCP | cs-gcp-auth | auth8 |
Examples of the API subdomain:
| Region | Pre-Production Environment | Production Environment |
|---|---|---|
| US AWS | cs-api6 | api6 |
| EU AWS | cs-api6.eu | api6.eu |
| US GCP | cs-gcp-api6 | api8 |
Tenant IDs are client specific and can only be provided by your Implementation Consultant or Client Success Manager.
In the CDP authentication process, a token is used as a shared secret that you use to generate access keys. You must store and manage tokens inside your firewall. Tokens must never be sent to the client browser or the frontend of the app.
You will be provided a webtag-specific user name and password for your CDP webtag client (typically in the form of a base64 encoded string for easier use) . Using this information you will make the following POST rest call to get your token:
https://<tokenManagementSubdomain>.agilone.com/token?action=create&scheme=a1webtag
Note
Content-Type set to application/json.Authorization set to Basic with the
user name and password provided by CDP. Provide these values
in the form of a base64 encoded string or separate user name and password
parameters.Example using cURL (with dummy credentials):
curl -X POST -H "Content-Type: application/json" -H "Authorization:
Basic r9CidGFnX2x1jERsZW1vbjpQaVRhNzczMiE5"
"https://<tokenManagementSubdomain>.agilone.com/token?action=create&scheme=a1webtag"
This call creates and returns a token and the expires_in attribute,
which represents the number of seconds left in token expiration. For example:
{
"access_token": "31e1a40b-ce25-2b67-a63d-52c460e544x33",
"token_type": "bearer",
"expires_in": 1805020,
"user": {
"tenantId": 999,
"username": "webtag_demo",
"userType": "CLIENT",
"passwordExpiryDate": "2017-07-26T00:00:00"
}
}
You must store this token behind your firewall and keep a track of its expiration. It is valid for a fixed period, typically 90 days. Therefore, you must request a new token from CDP before it expires. To request a new token from CDP, see Requesting a new token.
Possible API responses:
Status = 200 OK: the payload of the response is documented in the preceding screen.
Status = 400 Bad Request: user attempts to create a new token when the
maximum allowed three tokens are already created. The payload in the response
code contains the message: Active sessions for user have reached the set threshold. To create a new token, you must delete existing tokens. For
information, see Deleting tokens.
Status = 401 Unauthorized: the credentials are invalid because of a typo,
or the user doesn’t exist or doesn’t have the right access to the API. The
payload in the response contains the error code: INVALID_USER_CREDENTIALS
and a user-friendly message: Invalid username and/or password.
Status = 403 Forbidden: Typically happens if multiple login attempts are made with wrong credentials. The response payload contains:
{
"errorCode":"USER_DISABLED",
"userMessage":"User has been disabled",
"developerMessage":null,
"linkToErrorDoc":"",
"linkToResourceDoc":null,
"additionalInfo":null
}
If you need to check the time left on the newest token, or if you don’t know
what token is still valid, you can call the same endpoint using a GET request
and an authorization header of Authorization: Basic [yourCredentialsHere]
Example :
The response contains the token access_token as well the expiration
expires_in, in seconds from the time at which you executed the call.
Note
If you are unsure about when a specific token is about to expire, you can:
Call https://<tokenManagementSubdomain>.agilone.com/token?
scheme=a1webtag, using a GET request and an authorization header of
Authorization: Bearer [yourTokenHere].
Example using cURL (with dummy token value):
curl -X GET -H "Content-Type: application/json" -H "Authorization:
Bearer 8g263f43-5975-40c1-a818-ed35de08aag8"
"https://<tokenManagementSubdomain>.agilone.com/token?scheme=a1webtag"
If you reached the limit of three active tokens and you must remove some
tokens, you must make a DELETE request to the same endpoint using an
authorization header of Authorization: Bearer [yourTokenHere]. If you
forgot your tokens, you can use the
GET method to get the latest valid token.
After you retrieve that token, you can delete it and iterate to clear all
your tokens or request a new one.
Example using cURL (with dummy token value):
curl -X DELETE -H "Content-Type: application/json" -H
"Authorization: Bearer 8g263f43-5975-40c1-a818-ed35de08aag8"
"https://<tokenManagementSubdomain>.agilone.com/token?scheme=a1webtag".
When making calls to the CDP server like webtag, each call must have an access
key in the URL. When using the SDK to send webtags from your website, you
provide the key in the $A1Config variable and the SDK adds the key to calls
to the CDP server automatically.
To implement the webtag through pure API implementation, such as for an app or an integration with other vendors, you must append that key to all of your calls as an additional query-string parameter. For example,
accessKey=$2a$10$UZznrmUuKzT6FbmR1mADP.rscVdx.uM/S.0keoOaZ8oM68GXWzYKm
To produce the access key:
key attribute in the
$A1config variable used by your web pages. For other API
implementations, append that access key as a query-string parameter as
explained previously.Note
During your implementation and testing phase, CDP provides a staging environment so you can test the full flow, send test data to us for validation, and avoid polluting your CDP production environment with that data. This environment is commonly referred to as “CS” (as opposed to the production environment referred to as “PROD”), and here are some details about what needs to be tweaked to point to CS or to PROD once the validation is done.
CDP’s recommendation is to avoid hardcoding any of the variables below, and instead use configuration files to store those values so no code change is needed when you push from your development website/app to your production website/app.
For testing:
Once the validation is done, you can switch your production website/app to use the PROD authentication endpoint, with your PROD credentials (provided by your CDP Implementation team) and the same flow and calls.
To test your website implementation, update the values that you pass to
the $A1Config variable to ensure that the page has the following structure:
<!doctype html>
<html>
<head>
…
<script>
var $A1Config = {
key: "<yourAccessKey>",
tenantId: <yourTenantID>,
host: "//<apiSubdomain>.agilone.com"
};
</script>
<script src=”https://scripts.agilone.com/latest/a1.js”></script>
</head>
<body>
…
</body>
</html>
For testing, you must add the host element to the $A1Config variable. After
the validation is completed, you can remove the host parameter from
the $A1Config variable, or update the variable to the production subdomain.
Depending on your implementation (website or app/API), continue with the following articles:
53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842