Create an access token - Precisely Data Integrity Suite

Data Integrity Suite APIs

Product

Data_Integrity

Spatial_Analytics

Data_Enrichment

geo_addressing_1

Services

Spatial Analytics

Data Enrichment

Geo Addressing

ft:title

Data Integrity Suite APIs

ft:locale

en-US

PublicationType

pt_developer

copyrightfirst

2023

copyrightlast

2026

An access token is used by client applications to call the API.

For Data Integrity Suite APIs, the access token is transmitted in the HTTP Authorization header as a Bearer token. Bearer tokens inform a Data Integrity Suite API that the bearer of the token has been authorized to access the API and perform a predetermined set of actions specified by granted scopes.

An api_key:api_secret key pair is required to create an access token. So before you create the access token, make sure that you created at least one key pair and encode it as a Base64 string. Scripting and programming languages provide methods to perform the Base64 encoding. For trial purposes, there are also web applications that perform the Base64 encoding on a string.

The POST method is applied to the <root>/auth/v2/token endpoint to provide Basic authentication. The Base64 encoded api_key:api_secret key pair is passed in the Authentication header as a Basic authentication, like this:

Basic OWMxZGFmODA4ZTI1ZDQ5ZjpCdDAyZ2NpQjNYTjlac3U3eEZNVGJHU3NZZE5OQnBrZA==

The grant type and scope are specified by properties in the request body. The grant type client_credentials is for a Data Integrity Suite client application.

{
    "grant_type": "client_credentials",
    "scope": "default",
}

For trial examples, use the default scope. The token scope defines the specific permissions and access rights granted to an API token. These dictate what actions an application authenticated with a token is authorized to perform within an API or system. An application can request one or more scopes, and the access token issued to the application will be limited to the scopes granted. The default scope refers to a generic scope that encompasses all permissions provided to the workspace. You cannot specify other scopes with the default scope. In a production environment, developers typically specify scopes that provide only those permissions required by an application to complete its tasks.

The authentication method returns an access token in the body, along with the scope and how long the token is valid.

{
    "access_token": "eyJraWQiOiJNcXY2RWNBR0JNUElKbEdnRG1LYkNISC1fZkpaam4yWks4aU1lY3k...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "default"
}

The expires_in property specifies an interval in seconds until the token expires. In Data Integrity Suite, this is 60 minutes (3600 seconds). It is generally recommended to use the same access token for multiple API calls until it approaches expiration. To account for any time discrepancies between systems, you can renew the token a few seconds before it expires. For example, you could calculate a renewal time 5 seconds before the token expires and compare that with the current time before calling an API method with the token.

To create a token, you can make an API requests using cURL, Postman, or OpenAPI to call the Authentication API endpoint. All three methods require a valid API Key and Secret in Base64 format (Base64(api_key:api_secret). After you send the request, the resulting token is returned by the access_token property in the response body. Until the token expires, you can use it as a Bearer token for subsequent requests to Data Integrity Suite APIs. The expiration interval for the Data Integrity Suite token is 3600 seconds (60 minutes).

The examples in this section show how to use Postman, cURL, or OpenAPI to create an authentication token.

Authenticate using Postman
This example shows how to use Basic Authentication to create an authentication token in Postman.
Authenticate using cURL
This example shows how to use Basic Authentication to create an authentication token using cURL.
Authenticate using OpenAPI
This example shows how to use Basic Authentication to create an authentication token using OpenAPI.

Authenticate using Postman

This example shows how to use Basic Authentication to create an authentication token in Postman.

To authenticate in Postman, download the Postman environment and collection .json files. Go to the Post Man Collection, and follow the instructions to download the API collections file and instructions to configure your environment for your region (US, EU, AU1, or GB1). This section describes authentication using API Key Auth and the Bearer token.

Import the JSON collection.
Set up the Postman environment and choose the appropriate JSON environment file for your region.
Click Collections, and expand the DIS APIs collection.
Expand POST Generate Token, and open the Generate Token request.
You can let Postman populate the Authorization header or do it yourself.
Let Postman do it

Postman encodes the api_key:api_secret key pair and populates the Authorization header.
1. On the Authorization tab, for Auth Type, choose Basic Auth.
2. For Username, enter the API key name.
  
  Tip: Save the API key in a global, environment, or collection variable and reference the variable (such as {{api_key}}) instead of the actual API key value.
3. For Password, enter the API secret value.
  
  Tip: Save the API secret in a global, environment, or collection variable and reference the variable (such as {{api_secret}}) instead of the actual API secret value.
Do it yourself
1. On the Authorization tab, for Auth Type, choose No Authentication.
2. On the Headers tab, add an Authorization key.
3. In the Value column, enter "Basic" followed by the Base64 encoded API key and secret string, Basic base64(api_key:api_secret).
On the request Headers tab, make sure that only one Authorization header is selected.
Ensure that the Content-Type header is set to application/x-www-form-urlencoded.

Click Send.

If successful, the result Body tab displays these object properties:

{
    "access_token": "eyJraWQiOiJNcXY2RWNBR0JNUElKbEdnRG1LYkNISC1fZkpaam...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "default"
}

Confirm that the access_token value was copied into the authToken global variable.
The following code in Scripts, on the Post-response tab, copies the token to the authToken variable.
```
const jsonResponse = pm.response.json();
pm.globals.set("authToken", jsonResponse.access_token);
```
The authToken variable can used in Postman to authenticate other Precisely API endpoints until the token is replaced or expires.

Authenticate using cURL

This example shows how to use Basic Authentication to create an authentication token using cURL.

cURL request to obtain token

curl --location --request POST 'base-URL/auth/v2/token' \
--header 'Authorization: Basic base64(api_key:api_secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data-urlencode 'scope=default'

curl --location --request POST 'https://api.cloud.precisely.com/auth/v2/token' \
--header 'Authorization: Basic ORMaZGFmOMD4ZTI1ZDQ5ZjpNR0d2OTZES2h3QnQyRjVucjlxdkJRVHF4RVZDTHBTLg==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data-urlencode 'scope=default'

curl --location --request POST "base-URL/auth/v2/token" ^
--header "Authorization: Basic base64(api_key:api_secret)" ^
--header "Content-Type: application/x-www-form-urlencoded" ^
--data "grant_type=client_credentials" ^
--data-urlencode "scope=default"

curl --location --request POST "https://api.cloud.precisely.com/auth/v2/token" ^
--header "Authorization: Basic ORMaZGFmOMD4ZTI1ZDQ5ZjpNR0d2OTZES2h3QnQyRjVucjlxdkJRVHF4RVZDTHBTLg==" ^
--header "Content-Type: application/x-www-form-urlencoded" ^
--data "grant_type=client_credentials" ^
--data-urlencode "scope=default"

Note: If you receive an authentication error with status Invalid_key_secret, regenerate your API Key and Secret. This often resolves the problem.

Tip: The Linux and macOS operating systems uses the single quotation marks to delimit strings and the backslash to delimit multiline commands. The Windows Command Prompt uses double quotation marks to delimit strings, and the caret (^) to delimit lines. If double quotes are present within a Windows string argument, it must be escaped (\").

Authenticate using OpenAPI

This example shows how to use Basic Authentication to create an authentication token using OpenAPI.

In Swagger, use the authentication endpoint (base_url/auth/v2/token). To create a token, configure a POST request with these header keys:

Table 1. Request Header keys
Key	Type	Value	Description
Authorization	Header	`Basic base64(key:secret)`	The API `key:secret` pair, encoded in Base64.
Content-Type	Header	`application/x-www-form-urlencoded`	The format of the request body.

Make sure that the request body is set to JSON and add these request body object properties:

Table 2. Request body properties
Property	Type	Value
grant_type	String	`client_credentials`	Grant type for the token.
scope	String	`default`	Use `default` for the trial.