Information for: DEVELOPERS   PARTNERS   SUPPORT

Authentication for website and app implementations

Implementing the Customer Data Platform (CDP) webtag authentication

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:

  1. Use your user name and password to request a token.
  2. Generate an access key using the token.
  3. Send the access key as part of each request you make to the CDP webtag APIs.

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.

Requirements

Before you can integrate with CDP’s DW Tracker API, your Implementation Consultant (IC) must provide you with:

  • a webtag-specific user name and password for your CDP webtag client
  • your Tenant ID
  • the 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

Tenant IDs are client specific and can only be provided by your Implementation Consultant or Client Success Manager.

Obtaining and managing CDP tokens

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.

Requesting a new token

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

  • The subdomain changes during onboarding. For more information, see Setup for development and testing.
  • The header must have Content-Type set to application/json.
  • The header must have 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.
  • The password used for this authentication expires 90 days from the date of creation. The system renews the password automatically on the production environment. To extend your password on the CS environment, contact your CDP team.

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"
  }
}

POST request

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
    }
    

Managing existing tokens

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 :

GET request

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

  • For a specific environment, you can have maximum three active tokens at any time.
  • After requesting a new token, the existing token continues to work until its expiration, 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 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"
    

Deleting tokens

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".

Generating an access key

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:

  1. Append the current date in the UTC timezone to your CDP token: “yourToken” + “yyyy-mm-dd”, e.g. “yourToken2020-05-01”.
  2. 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 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

  • 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

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 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.

Authentication

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 (provided by 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/app to use the PROD authentication endpoint, with your PROD credentials (provided by your CDP Implementation team) and 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 is completed, you can remove the host parameter from the $A1Config variable, or update the variable to the production subdomain.

Next steps

Depending on your implementation (website or app/API), continue with the following articles: