Overview

To perform catalog operations using the Alation API, you must first generate 2 API tokens, Refresh & Access token respectively. API tokens can be created by each logged-in user in order to use the APIs accessible to their Alation role. Check APIs by Roles for the most update to date permissions by role.

Check out Refresh & Access Token Overview for additional details.

Terminology

RefreshToken: A long living token the users can use to manage and create API Access Tokens, which can be used to interact with the other Alation APIs.
APIAccessToken: A short-lived access token, which can be passed as the value for the 'TOKEN' header in the requests for other Alation APIs.

Creating API tokens is a two-step process. First, you need to create a Refresh token, and then use it to create a short-lived API Access token. The API Access token you generate must be used in the header of your API request as the value of the TOKEN parameter.

Life Span

The lifetime of API tokens is configurable per Alation instance and can be set up in accordance with the Organization’s policies. An Alation Server Admin can configure the default life space of the tokens by following the Configure the API Tokens Management guide.

Refresh token is valid for 60 days
API Access Token is valid for 24 hours

Note

It is possible to create multiple Refresh tokens, if necessary. Multiple Refresh tokens can be created if you plan to create several different integrations using the Alation API. Each separate RefreshToken can be dedicated to an application or connection, which will help keep the integrations isolated and avoid breaking other integrations.

API Tokens can be created either from the Alation Catalog UI or with the dedicated Refresh & Access Token Overview.

Create via UI

Create Refresh Token

To generate API tokens from the Alation Catalog (user interface):

In the Alation Catalog, click the user avatar on the upper right and in the menu that opens, click Account Settings.

On the Account Settings page that opens, click the Authentication tab. Tokens can be generated from the Access Tokens section on this tab:

If you are creating tokens for the first time, the Access Token section is empty. Click the Create Refresh Token button to create a new Refresh token:

In the Create Refresh Token dialog that opens, specify a name for the Refresh Token. You can give a name that describes your integration or specifies the purpose of this token. After providing a name, click Create Refresh Token.
Next, the Token Secret Key is displayed. Copy the Token Secret Key by clicking the Copy button.

Important

When this dialog is closed, the Token Secret Key will not be visible in the Alation UI and there is no way to reveal it. Store the copied Key securely.

You have an option to immediately create an Access Token from this Refresh token without closing the dialog. Alternatively, you can create an Access token later from the Account Settings > Authentication > Access Tokens section. To create an Access token immediately, click the Create API Access Token section in the dialog, To create an Access token later, click Done to close the dialog.
If you chose to immediately create an Access token, then in the Create API Access Token dialog that opens, click the Create API Access Token button. Note that the name of the Access token is prepopulated with the corresponding Refresh token name and cannot be edited:

Next, the Token Secret Key is displayed. Copy the key using either the Copy or Copy Key to Clipboard buttons and store it securely. This Secret Key must be provided as the value for the TOKEN parameter when sending requests to the Alation API. When this dialog is closed, the Token Secret Key will not be visible in the Alation UI and there is no way to reveal it:

After copying the Token Secret Key, click Done. You are navigated to the Account Settings > Authentication tab. The Refresh token you created is now listed under the Access Tokens section:

View Available Refresh Tokens

The Refresh tokens created by a user are listed under the Access Tokens section on Account Settings > Authentication tab. For each Refresh token, you can view:

Token Name
Creation Date
Token Status
Expiration time
Access Token availability and status

If you have already created an Access token for a specific Refresh token, the API Access Token Status column will reflect the status of the respective Access token (Active, Expired, or Revoked). If an Access token has not been created yet, the API Access Token Status column will be empty, and you will see the Create API Token link in the Actions column:

Create API Access Token

API Access Tokens can be created from the Account Settings > Authentication > Access Tokens section.

Under the Access Tokens section, locate the Refresh token you need and click Create API Token in the Actions column.
In the Create API Access Token dialog that opens, click Create API Access Token.
Next, the Token Secret Key is displayed. Copy and securely store the Token Secret Key.

Important

When this dialog is closed, the Token Secret Key will not be visible in the Alation UI and there is no way to reveal it.
After copying the Secret Key, click Done. You are navigated back to the Account Settings > Authentication page. The API Access Token Status column will now display the status of the API Access Token as Active.

Regenerate API Access Token

When your API Access Token expires or if you misplace the Token Secret Key for the Access Token, you can regenerate the token.
To regenerate, click the Regenerate API Token for the corresponding Refresh token in the Tokens table. Then create a new API token.

Important

Remember to copy and store the Token Secret Key. It will not be visible in the Alation UI after the Create API Access Token dialog is closed and there is no way to reveal it.

Please refer to the API documentation for details about this API.

Manage Users’ API Tokens

A Server Admin can view API tokens created by users and revoke those tokens, if necessary. API tokens can be revoked on the Users tab of the Admin Section: Revoke API Tokens .

Create Programmatically

Create Refresh Token

📘
If you use single sign-on (SSO) to log into Alation, then you don't have a password and therefore can't create a refresh token programmatically. See the instructions above for creating a refresh token using the Alation UI.

Using your account, pass these credentials to the refresh token API. Example using Python:

import requests

BASE_URL = "https://YOUR_CATALOG_URL_HERE"
api_url = "/integration/v1/createRefreshToken/"
# Replace email_address_here and password_here with your email and password
data = {
  "username": EMAIL_ADDRESS_HERE,
  "password": PASSWORD_HERE,
  "name": project_name_here # can be anything, e.g. AlationAPI
}

# Get refresh token
response = requests.post(BASE_URL + api_url, json=data)
print(response.json())

{
  "refresh_token": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
  "user_id": 102,
  "created_at": "2021-12-31T01:04:47.035Z",
  "name": "TableauRefreshToken",
  "token_expires_at": "2021-12-31T01:04:47.035Z",
  "token_status": "active"
}

If you're wanting to store the refresh token, make sure you take note of "token_expires_at" and "user_id" in the response.

API Access Token - Create

Using the refresh token, create an access token. Example using Python:

import requests

BASE_URL = "https://YOUR_CATALOG_URL_HERE"
api_url = "/integration/v1/createAPIAccessToken/"
# Replace user_id and refresh_token values with your user id and refresh token
data = {
    "refresh_token": "YOUR_REFRESH_TOKEN_HERE",
    "user_id": 102
}

# Get APIAccessToken for user using the RefreshToken
response = requests.post(BASE_URL + api_url, json=data)
print(response.json())

{
  "api_access_token": "e25388fde8290dc286a6164fa2d97e551b53498dcbf7bc378eb1f178",
  "user_id": 102,
  "created_at": "2021-12-31T17:43:04.616Z",
  "token_expires_at": "2021-12-31T17:43:04.616Z",
  "token_status": "active"
}