Overview

Alation provides two ways of authenticating API calls:

• JWT tokens with OAuth 2.0
• API keys

JWT Tokens with OAuth 2.0

For Alation Cloud Service customers on the cloud-native architecture, Alation offers the ability to authenticate Alation API calls securely using JWT tokens. This enables you to authenticate programmatically (machine to machine) using an access token, without requiring user credentials. You can also verify tokens online or offline, revoke tokens, and rotate signing keys for increased security.

This process requires you to create an OAuth client application within Alation. You'll associate a system user with the client application and give the system user an Alation role to determine what types of API calls they are authorized to make.

For complete details on how to authenticate with JWT tokens and OAuth 2.0, see Authenticate API Calls with OAuth 2.0 in the Alation user documentation, then see the OAuth 2.0 API to create a JSON web token.

API Keys

API keys can be created by any user who's logged into Alation. When the API key is sent along with an API call, the key is validated on the Alation server, and the user is authorized to execute API calls that are allowed by their Alation user role. See APIs by Roles to see what APIs can be used by each role.

Token Types

To authenticate with API keys, you must generate two tokens:

• Refresh token: A long living token used to manage and create API access tokens.
• API access token: A short-lived access token, which can be passed as the value for the TOKEN header in the requests for Alation APIs.

Token Lifespan

Tokens have a lifespan, after which they expire and are no longer valid. The following table shows the default lifespans.

The lifespan of API tokens is configurable. To change the default lifespan, see Configure the API Tokens Management Feature.

📘

Multiple Tokens

It is possible to create multiple refresh tokens, if necessary. For example, if you plan to create several different integrations using the Alation API, a separate refresh token can be dedicated to each application or connection. This can 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 API.

Create a Refresh Token

You can create a refresh token using the Alation API or the Alation UI. Both methods are described below.

📘

Creating a refresh token when using SSO

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 for creating a refresh token using the Alation UI.

Create a Refresh Token via the API

Using the Create Refresh Token endpoint, pass your user credentials to the API.

Here's a simple 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"
}

Here's a more advanced example using Python:

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

Create a Refresh Token via the UI

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

1. In the Alation Catalog, click the user avatar on the upper right and in the menu that opens, click Account Settings or Profile Settings.
2. On the Account Settings page that opens, click the Authentication tab.
3. To create a new refresh token, click the Create Refresh Token button.
4. 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.
5. After providing a name, click Create Refresh Token. The Token Secret Key is displayed. Copy the Token Secret Key by clicking the Copy button.

🚧

Warning

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.

6. You have an option to immediately create an API access token from this refresh token without closing the dialog. 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.
7. 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.
8. 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 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.

🚧

Warning

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.

9. 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 the 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 an API Access Token

You can create an API access token using the Alation API or the Alation UI. Both methods are described below.

Create an API Access Token via the API

Using the Create Access Token endpoint, pass your refresh token to the API.

Here's a simple 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"
}

Create an API Access Token via the UI

To create an API access token:

1. Go to Account Settings > Authentication > Access Tokens.
2. Under the Access Tokens section, locate the refresh token you need and click Create API Token in the Actions column.
3. In the Create API Access Token dialog that opens, click Create API Access Token.
4. The Token Secret Key is displayed. Copy and securely store this key.

🚧

Warning

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.

5. After copying the Token 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 an API Access Token via the UI

When your API access token expires or if you misplace the token's secret key, you can regenerate the token.
To regenerate:

1. Go to Account Settings > Authentication > Access Tokens.
2. Under the Access Tokens section, locate the refresh token you need and click Regenerate API Token in the Actions column.
3. In the Create API Access Token dialog that opens, click Create API Access Token.
4. The Token Secret Key is displayed. Copy and securely store this key.

🚧

Warning

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.

5. After copying the Token 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.

Revoke Users' Tokens as an Admin

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 Settings page: Revoke API Tokens.