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:
- Use your user name and password to request a token.
- Generate an access key by using the token.
- Send the access key as part of each request you make to the CDP WebTag APIs.
- Call the logout API endpoint to log out of the session.
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.
Requirements
Before you can integrate with CDP’s DW Tracker API, Acquia provides you with:
- WebTag-specific user name and password for your CDP WebTag client
- Tenant ID
- Token management and API subdomains for the production and pre-production environments of your account’s CDP region.
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. Only your implementation consultant (IC) or customer value manager (CVM) can provide the tenant IDs.
Obtaining and managing CDP tokens
In the CDP authentication process, a token is used as a shared authenticator 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 application.
Requesting a new token
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:
API endpoint
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
- The subdomain changes during onboarding. For more information, see Setup for development and testing.
- The header must have
Content-Typeset toapplication/json. - The header must have
Authorizationset toBasicwith the user name and password provided by CDP. Provide these values in the form of abase64encoded string or separate user name and password parameters. - Typically, the password used for authentication expires 90 days from the date of creation. However, this value is configurable and if you want to update the time after which the password expires, contact your CVM or IC. The system renews the password automatically on the production environment. To extend your password on the CS environment, contact your CDP team.
Response 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 CVM or IC. You must create a new token before the earlier token expires.
The following is a sample image with API request and response in Postman:
The following is the 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"
}
}
The following are the 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 thresholdmessage. 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_IDerror code and theInvalid token identifiermessage. The system auto-deletes inactive or expired tokens. - Status = 403 Forbidden: API error code when you login with wrong credentials multiple times.
500: This status code indicates a generic server error. Acquia recommends you to retry pushing the data.
{ "errorCode":"USER_DISABLED", "userMessage":"User has been disabled", "developerMessage":null, "linkToErrorDoc":"", "linkToResourceDoc":null, "additionalInfo":null }
Managing existing tokens
If you need to check the time left on the newest token, or if you want to check the token is still valid, you can call the same endpoint using a GET request and an authorization header of Authorization: Basic [yourCredentialsHere]
For example :
The response contains the token access_token and the expiration expires_in, in seconds from the time at which you executed the call.
Note
- For a specific environment, you can have a maximum of three active tokens at any time.
- After requesting a new token, the existing token continues to work until it expires, unless you revoke it. Ensure that you have at most two active tokens at any time. Otherwise, when the next request hits the maximum number of allowed tokens, you must delete a token or wait for another one to expire.
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 the Authorization: Bearer [yourTokenHere] authorization header.
The following is an example of 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"
The following is the API response code:
- Status = 400 SESSION_INFO_NOT_FOUND occurs when unexpired tokens are not available.
Managing active tokens
If you reach the limit of three active tokens, you must remove some of the tokens to proceed. Submit a DELETE request to the same endpoint using the Authorization: Bearer [yourTokenHere] authorization header.
Detecting the token limit
When you exceed the active token limit, the API response displays an error message.
The following is an example of the error message:
{
"errorCode": "ACTIVE_SESSIONS_THRESHOLD_REACHED",
"userMessage": "Active sessions for user have reached the set threshold. Please use an existing token.",
"developerMessage": "98fa5c5c-5581-486f-a290-a75b4f112a33",
"linkToErrorDoc": "",
"linkToResourceDoc": null,
"additionalInfo": null
}The following are the details of the error:
- Error code:
ACTIVE_SESSIONS_THRESHOLD_REACHED - User message:
Active sessions for user have reached the set threshold. Please use an existing token.
This error indicates that the maximum limit of three active tokens is reached.
Complete the following steps to resolve the error:
| S.No. | Step | Description |
|---|---|---|
| 1 | Retrieve active tokens | To retrieve the list of active tokens and get the latest valid token, use the GET method. For more information, visit Manage existing tokens. |
| 2 | Delete excess tokens | To delete the excess tokens:
The following is an example using cURL with dummy token value: |
| 3 | Acquire new tokens | After all excess tokens are deleted, you can request new ones as required. |
Generating an access key
When making calls to the CDP server, such as WebTag, each call must have an access key in the URL. When using the SDK to send WebTags from your website, you must provide the key in the $A1Config variable. The SDK adds the key to call 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:
- Append the current date in the UTC timezone to your CDP token: “yourToken” + “yyyy-mm-dd”. For example, “yourToken2020-05-01”.
- Hash this value using the bcrypt hash with 10 rounds. The resulting hash is your access key. For a website implementation using the SDK, compute the key and add it in the
keyattribute in the$A1configvariable used by your web pages. For other API implementations, append that access key as a query-string parameter as explained earlier.
Note
- Access keys are valid for 24 hours after the yyyy-mm-dd input date (UTC timezone) used to generate them. This provides you time to transition your key each day.
- This access key is not user-specific. You must generate a new access key every day, and use it for all users and sessions.
- Each of your web or app pages must get this access key from a secure location on your web or app server. The token used to generate the access key must never be sent to the client browser or the frontend of the app.
Summary
Setup for development and testing
During your implementation and testing phase, CDP provides a staging environment so you can test the full flow, send test data to CDP for validation, and keep your CDP production environment clean. This environment is commonly referred to as CS. The production environment is referred to as PROD.
Acquia recommends avoiding hard coding any of the variables. You can use configuration files to store these values. Therefore, you do not need to change the code when you push from your development website or application to your production website or application.
Authentication
The following are the important points for testing:
- The behavior that includes response and errors of this endpoint, the authentication calls, and the flow described in Summary are the same in CS and PROD.
- You need to use the CS authentication endpoint
- This endpoint requires a CS-specific set of credentials. You can get these credentials from your CDP Implementation team.
- This endpoint provides you with CS-specific tokens, which are not relevant or usable in PROD.
Once the validation is done, you can switch your production website or application to use the PROD authentication endpoint. You can use the PROD credentials. You can get these credentials from your CDP Implementation team. You can follow the same flow and calls.
Adding the webtag to your pages
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, you can remove the host parameter from the $A1Config variable, or update the variable to the production subdomain.
Next steps
Read the following depending on your implementation:
- For your website, see Adding the webtag to your website.
- For an application or other API implementation, see Using the webtag tracker API.