---
title: "API Authentication Process"
date: "2024-03-08T11:43:35+00:00"
summary:
image:
type: "page"
url: "/customer-data-platform/api-authentication-process"
id: "f9f43d82-7f71-4d66-b264-c02836f5c7c0"
---

This page provides information about the API authentication process for the following scenario:

Data engineers want to understand the complexities of the CDP REST API to create efficient integrations within the business architecture through self-service integration tools. They also want to develop and execute data integration tasks to enhance autonomy and reduce dependency on specialized technical knowledge.

The following are the ways to achieve this scenario:

*   [Self-service UI](#self-service-api)
*   [Postman](#postman-api)

Creating a user role through the self-service UI
------------------------------------------------

Before you start creating a user role, you must get access to the **Instances** user interface by contacting your CDP administrator.

To create a user role:

1.  [Sign in to the CDP user interface](/customer-data-platform/getting-started/signin-cdp).
2.  Click **Integrations** > **Instances**.
3.  Click **Add Instance**.
    
    The system displays the Create Instance page.
    
4.  In **Name**, enter the name for your instance.
5.  In **Instance Type**, select one of the following:
    *   **DW Tracker** to push upstream payloads from a source system to CDP.
    *   **360 Profiles** to pull downstream payloads from CDP to a source system.
        
        ![cdp_api-create-instance.png](https://acquia.widen.net/content/1667aa38-b500-4004-b7f0-61236b7fa824/web/cdp_api-create-instance.png?w=480&itok=PVX3qn1R)
        
6.  Click **Save**.
    
    The system creates the instance and auto-populates values in the following fields:
    
    *   **API Host URL**
    *   **Authentication Host URL**
    *   **UserName**
    *   **Password**
7.  Take a backup of these credentials at a secure location as you cannot view them in the system again.
    
    These credentials are used when creating a user role through Postman.
    
    ![cdp_api-creds.png](https://acquia.widen.net/content/53ce2a45-4bce-4333-a44d-07d73c97706e/web/cdp_api-creds.png?h=480&itok=BMajq9Gh)
    

Creating a user role through Postman
------------------------------------

Complete the following tasks to create a user role through Postman for the given scenario:

S.No.

**Task**

1

[Set up Postman](#set-up-postman)

2

[Set up the Authentication request](#set-up-auth-request)

3

[Set up the Token Retrieve request](#set-up-token-retrieve-request)

4

[Set up the Token Extend request](#set-up-token-extend-request)

5

[Set up the Token Create request](#set-up-token-create-request)

6

[Set up the Token Delete request](#set-up-token-delete-request)

7

[Set up the All Token Delete request](#set-up-token-delete-all-request)

### Setting up Postman

1.  Download and open [Postman](https://www.postman.com/downloads/).
2.  Click **Create Collection**.
    
    ![cdp_api-postman-create-collection.png](https://acquia.widen.net/content/33db649d-b7e2-4003-a665-2b2e8cf6739f/web/cdp_api-postman-create-collection.png)
    
3.  Click the ellipsis icon, click **Rename**, and then rename the folder collection to **CDP Authentication**. 
    
    Postman displays the CDP Authentication collection.
    

### Setting up the Authentication request

1.  In the **CDP Authentication** collection, click **Add a request**.
    
    ![cdp_api-postman-add-request.png](https://acquia.widen.net/content/6b31a96f-f852-4ec1-bdb6-70c0123b2091/web/cdp_api-postman-add-request.png?w=480&itok=Umz5-0aG)
    
2.  Click the ellipsis icon, click **Rename**, and then rename the request to **Step 1 - Authenticate with Username and Password (One Time)**.
3.  Change the request to `POST`.
    
    ![cdp_api-postman-post.png](https://acquia.widen.net/content/645db065-9427-43aa-8e05-78d6eab8e554/web/cdp_api-postman-post.png)
    
4.  In **Enter URL or paste text**, enter the credentials that you generated while [creating a user role through self-service UI](#self-service-api).
    
    Ensure the URL matches your cloud region and tenant type as saved earlier.
    
    For example, `https://auth.agilone.com/authentication?action=login`.
    
    The following are the URL parameters:
    
    **Cloud Region**
    
    **URL Endpoint**
    
    **Parameter Description**
    
    AWS
    
    `auth.agilone.com`
    
    *   `/authentication` indicates the path that directs the request to the authentication service on the server.
        
    *   `?` indicates the beginning of the query string, which contains the parameters.
        
    *   `action=login` indicates the parameter that specifies the action. It informs the server that the intention of the request is to initiate a login process.
        
    
    Postman auto-populates the value on the **Params** tab.
    
    ![cdp_api-postman-params.png](https://acquia.widen.net/content/4064154f-4a8e-475f-8911-d519c8a07d1f/web/cdp_api-postman-params.png)
    
5.  Click the **Authorization** tab and select the **Type** as **Basic Auth**. 
    
    ![cdp_api-postman-basic-auth.png](https://acquia.widen.net/content/f7f681e5-c3e2-43a9-b09a-5f5187e1725d/web/cdp_api-postman-basic-auth.png?h=480&itok=VVoxGUdt)
    
6.  Enter the username and password.
    
    ![cdp_api-postman-authorization.png](https://acquia.widen.net/content/d60276d7-c6ce-4e9f-9ad2-863b5d8b60fe/web/cdp_api-postman-authorization.png)
    
    Postman recommends that you save all sensitive information into variables. For more information, visit [Store and reuse values using variables](https://learning.postman.com/docs/sending-requests/variables/variables/).
    
    If you cannot set up variables, delete the sensitive information and re-enter the credentials each time you need, so that you can conduct tests to avoid security risks.
    
7.  Click the **Headers** tab.
    
8.  Add **Key** as **Content-Type** and **Value** as **application/json**.
    
    ![cdp_api-postman-hearders.png](https://acquia.widen.net/content/50c1670e-3c87-46f0-ae6a-e06b156c2b14/web/cdp_api-postman-hearders.png)
    
9.  Click **Save** and click **Send**.
    
    ![cdp_api-postman-save-send.png](https://acquia.widen.net/content/cdd38dfd-3e00-4c16-8815-7e0a2891b28f/web/cdp_api-postman-save-send.png?w=220&itok=JbDuXf6I)
    
    For successful requests, Postman displays **Status: 200 OK** and **access\_token**.
    
    ![cdp_api-postman-access-token.png](https://acquia.widen.net/content/4e13a1f0-02d4-4711-af92-4b52158a8b05/web/cdp_api-postman-access-token.png)
    
    You can initiate the user authentication step only after creating a token. You can use the token until it expires. You must not resend the request for continued testing with the generated token.
    

### Setting up the Token Retrieve request

When you use the REST API Authentication mechanism, you perform the request daily to retrieve the token until it expires. 

To retrieve a token:

1.  Click the ellipsis icon and click **Duplicate** to make a copy of the **Step 1 - Authenticate with Username and Password (One Time)** authentication request.
    
    ![cdp_api-postman-duplicate.png](https://acquia.widen.net/content/732309c3-d347-421a-9e98-cb5a120da1fd/web/cdp_api-postman-duplicate.png?h=480&itok=N5HiwXyF)
    
2.  Click the ellipsis icon, click **Rename,** and rename the copy of the authentication request to **Step 2 - Request Access Token (Daily)**.
3.  Change the request to `GET`.
    
    ![cdp_api-postman-get-request.png](https://acquia.widen.net/content/8b5aacee-2333-445d-b87a-a940a6810e8d/web/cdp_api-postman-get-request.png)
    
4.  Enter the Authentication mechanism endpoint URL as `https://auth.agilone.com/token?scheme=a1user`.
    
    The following are the URL parameters:
    
    Cloud Region
    
    URL Endpoint
    
    Parameter Description
    
    AWS
    
    `auth.agilone.com`
    
    *   `/token` indicates the path that directs the request to a service or resource on the server that deals with token generation or management.
        
    *   `?` indicates the beginning of the query string, which contains the parameters.
        
    *   `scheme=a1user`  indicates a parameter that specifies the authentication or authorization scheme. It tells the server that the request is created under the `a1user` scheme, possibly affecting how the token is generated or what permissions are associated with it. 
        
    
    Postman auto-populates the value on the **Params** tab.
    
5.  Click the **Authorization** tab and ensure that the **Type** is **Basic Auth**.
    
6.  Perform Steps 6 to 8 from [Setting up the Authentication request](#set-up-auth-request).
    
7.  Click **Save** and click **Send**.
    
    For successful requests, Postman displays **Status: 200 OK** and **access\_token**.
    
    Ensure to check the expiration date of the token on a regular cadence through GET request calls. The `expires_in` field in the response body indicates the lifespan of the token. By default, tokens last 90 days in Customer Sandbox (CS) and 180 days in UAT and Production (PROD) environments.
    

The response body consists of the following parameters:

Parameter

Description

`access_token`

A unique string that serves as a token for accessing protected resources. In this case, `"f265e508-c599-44e3-ab60-60a040a9154a"` is the token that the API returns. You must include this token in the header of subsequent requests to access authorized resources.

`token_type`

The type of token that is issued by the server. In this example, the token type is `"bearer"`, which means that the bearer of this token has the authorization to access the resources. Bearer tokens are a common method used in OAuth 2.0 for accessing resources.

`expires_in`

The lifetime of the access token in seconds. Once this time elapses, the token expires and no longer grants access. In this case, `15600000` seconds means the token has a significant duration before expiration. 

`tenantId`

The identifier for the tenant or account that you want to access.

`username`

The username of the user. In this case, the username is `"tracker_XXXXXX"`.

`userType`

The role or type of the user within the system. `"CLIENT"` indicates that the user has client-level access.

`passwordExpiryDate`

The expiry date of the user's password, necessitating a password change. Postman displays it in ISO 8601 format. For example,  `"2025-01-06T00:00:00"` indicates that the expiry date is January 6, 2025.

### Setting up the Token Extend request

If a token is about to expire, you can extend it for the next 180 days. Acquia recommends you to recycle the token by generating a new token. For more information, see [Setting up the Token Create request](#set-up-token-create-request). You may use the token for up to 1 year or longer as per your company's policies. 

To extend the token:

1.  Click the ellipsis icon and click **Duplicate** to make a copy of the **Step 2 - Request Access Token (Daily)** authentication request. 
2.  Click the ellipsis icon, click **Rename**, and rename the copy of the authentication request to **Extend - Current Token**.
3.  Change the request to `POST`.
    
    ![cdp_api-postman-extend-post.png](https://acquia.widen.net/content/44c2726d-e206-46e7-a377-70cca6acb68f/web/cdp_api-postman-extend-post.png)
    
4.  Enter the Authentication mechanism endpoint URL as `https://auth.agilone.com/token?scheme=a1user&action=extend`.
    
    The following are the URL parameters: 
    
    **Cloud**
    
    **URL Endpoint**
    
    **Description**
    
    AWS
    
    `auth.agilone.com`
    
    *   `/token` indicates the path that directs the request to a service or resource on the server that deals with token generation or management.
        
    *   `?` indicates the beginning of the query string, which contains the parameters.
        
    *   `scheme=a1user` indicates a parameter that specifies the authentication or authorization scheme. It tells the server that the request is created under the `a1user` scheme, possibly affecting how the token is generated or what permissions are associated with it. 
        
    *   `&` indicates that you can add multiple key-value pairs to the query string.
        
    *   `action=extend` indicates an action request to the server to extend the validity of the current token. This means the request is asking the server to prolong the lifespan of an existing token under the specified scheme `a1user`.
        
    
    Postman auto-populates the value on the **Params** tab.
    
5.  Click the **Authorization** tab and select the **Type** as **Bearer Token**.
    
    ![cdp_api-postman-extend-auth.png](https://acquia.widen.net/content/573e62c7-3ece-4001-a8b6-a63bc8c094aa/web/cdp_api-postman-extend-auth.png)
    
6.  Add the token that you want to extend.
7.  Perform Steps 7 and 8 from [Setting up the Authentication request](#set-up-auth-request).
    
    For successful requests, Postman displays **Status: 200 OK** and **access\_token**.
    
    Before Extend request:
    
    ![cdp_api-postman-before-token-extend.png](https://acquia.widen.net/content/91702a58-cdc0-406e-af0b-f8530ed800d4/web/cdp_api-postman-before-token-extend.png)
    
    After Extend request:
    
    ![cdp_api-postman-after-token-extend.png](https://acquia.widen.net/content/87fa02b3-a3a3-4a7b-a4f8-afd733d731f1/web/cdp_api-postman-after-token-extend.png)
    

### Setting up the Token Create request

Use this procedure only if the existing token is about to expire.

To create a token:

1.  Click the ellipsis icon and click **Duplicate** to make a copy of the **Step 3 - Request Access Token (Daily)** authentication request. 
2.  Click the ellipsis icon, click **Rename**, and rename the copy of the authentication request to **Create - Token**.
3.  Change the request to `POST.`
4.  Enter the Authentication mechanism endpoint URL as `https://auth.agilone.com/token?scheme=a1user&action=create`.
    
    The following are the URL parameters:
    
    **Cloud**
    
    **URL Endpoint**
    
    **Description**
    
    AWS
    
    `auth.agilone.com`
    
    *   `/token` indicates the path that directs the request to a service or resource on the server that deals with token generation or management.
        
    *   `?` indicates the beginning of the query string, which contains the parameters.
        
    *   `scheme=a1user` indicates a parameter that specifies the authentication or authorization scheme. It tells the server that the request is created under the `a1user` scheme, possibly affecting how the token is generated or what permissions are associated with it.
        
    *   `&` indicates that you can add multiple key-value pairs to the query string.
        
    *   `action=create` indicates an action request to the server to create a token. 
        
    
    Postman auto-populates the value on the **Params** tab.
    
5.  Click the **Authorization** tab and select the **Type** as **Basic Auth**.
6.  Add the token that you want to extend.
7.  Perform Steps 7 and 8 from [Setting up the Authentication request](#set-up-auth-request).
    
    For successful requests, Postman displays **Status: 200 OK** and **access\_token.**
    

### Setting up the Token Delete request

To delete a token:

1.  Click the ellipsis icon and click **Duplicate** to make a copy of the **Extend - Current Token** authentication request. 
2.  Click the ellipsis icon, click **Rename**, and rename the copy of the authentication request to **Revoke - A Token**.
3.  Change the request to `DELETE`.
    
    ![cdp_api-postman-delete-request.png](https://acquia.widen.net/content/a3271428-3d86-4b67-a37b-a6e130caa037/web/cdp_api-postman-delete-request.png)
    
4.  Enter the Authentication mechanism endpoint URL as `https://auth.agilone.com/token?scheme=a1user`.
    
    For more information, see the URL Parameter table in [Setting up the Token Retrieve request](#set-up-token-retrieve-request). 
    
5.  Click the **Authorization** tab and ensure that the **Type** is **Bearer Token**.
6.  Enter the token that you want to delete.
7.  Perform Steps 7 and 8 from [Setting up the Authentication request](#set-up-auth-request).
    
    Postman deletes the token.
    
    ![cdp_api-postman-delete-success.png](https://acquia.widen.net/content/6483feae-cf3b-481c-8a83-95d5a579251e/web/cdp_api-postman-delete-success.png)
    

### Setting up the All Token Delete request

To delete all tokens:

1.  Click the ellipsis icon and click **Duplicate** to make a copy of the **Revoke - A Token** authentication request.
2.  Click the ellipsis icon, click **Rename**, and rename the copy of the authentication request to **Revoke All Access Tokens**.
3.  ### Change the request to `DELETE`.
    
4.  ### Enter the Authentication mechanism endpoint URL as `https://auth.agilone.com/token?scheme=a1user`.
    
    For more information, see the URL Parameter table in [Setting up the Token Retrieve request](#set-up-token-retrieve-request). 
    
5.  ### Click the **Authorization** tab and select the **Type** as **Basic Auth**.
    
6.  ### Enter the username and password.
    
7.  Perform Steps 6 to 8 from [Setting up the Authentication request](#set-up-auth-request).
    
    Postman deletes all the tokens.
    

Summary
-------

You can use the REST API authentication mechanism to construct upstream and downstream data payload samples for each user role:

*   **Integration Users**: Create near real-time, event-based, or batch delta integrations.
    
*   **WebTag Service Users**: Create near real-time front-end for your website using the tracking pixel integration.
    
*   **360 Profile Users**: Retrieve the post processed records that are cleansed, aggregated, and deduped to form unified customer records.
    

CDP provides the following resources:

*   A prebuilt library for advanced developers
    
*   Import the Postman guide library, which requires the following files:
    
    *   The Product API Guide: Contains all clouds, environments, user roles, requests, and both upstream and downstream scenarios.
        
    *   Environments Globals: Contains all prebuilt dynamic variables, enabling you to test across various clouds, environments, and user roles without the need to duplicate folders or requests.