CDP uses a query string authentication scheme. All calls made to the CDP webtag APIs contain information to authenticate their source.
To authenticate your websites or apps with CDP through CDP webtag APIs:
This article contains examples of these steps by using Postman or cURL. Postman is a REST API client and cURL is 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, Acquia provides 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 |
Note
Tenant IDs are client specific and can only be provided by your IC or CSM.
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 front-end of the app.
CDP provides you with a webtag-specific user name and password for your CDP
webtag client. Typically, this is in the form of a base64 encoded string for
easier use. You must leverage this information to make the following ReST call
to generate a token:
https://<tokenManagementSubdomain>.agilone.com/token?action=create&scheme=a1webtag
Sample cURL command with dummy credentials:
curl -X POST -H "Content-Type: application/json" -H "Authorization:
Basic r9CidGFnX2x1jERsZW1vbjpQaVRhNzczMiE5"
"https://cs-auth.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.This API call creates and returns a token. You must store this token behind
your firewall. In addition, this call returns the expires_in attribute.
This attribute indicates the number of seconds left for token expiration. You
must keep a track of the token expiration. It is valid for a fixed period,
typically 181 days or 260000 minutes. However, this attribute is configurable
and if you want to update it, contact your CSM or IC. You must create a new
token before the earlier token expires.
Sample image with API request and response in Postman:
Sample response code:
{
"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"
}
}
Possible API responses:
Status = 200 OK: API success code when a token is created.
Status = 400 Bad Request: API error code when the user attempts to create
a token although the maximum allowed three tokens are already created. The
payload in the response contains the Active sessions for user have reached the set threshold user-friendly message. To create a token, you must delete
existing tokens. For more information, see Deleting tokens.
Status = 401 Unauthorized: API error code when a token expires. The
system returns the same code when there is no active token. The payload in the
response contains the INVALID_TOKEN_ID error
code and the Invalid token identifier user-friendly message. Note that
the system auto-deletes inactive or expired tokens.
Status = 403 Forbidden: API error code when 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