Token Authentication and Management APIs

Public APIs for managing RefreshTokens and APIAccessTokens for the user.

📘

If your organization is using SSO, like Okta, etc., then you will need to use the Alation UI to create a RefreshToken by going to <BASE_URL>/account/auth.

Description

• APIAccessToken: A short-lived access token, which can be passed as the value for the 'TOKEN' header in the requests for other Alation APIs.
• 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.

Expiration Times

The default expiration times for RefreshToken and APIAccessToken are 60 days and 24 hours respectively. They can be configured using the alation_conf by the Server Admins if you need different expiration times.

To change the Refresh Token expiration time, log in to the Alation server, and using alation_conf, update the RefreshToken lifespan (in days). For example, the following command sets the expiration time for any new RefreshTokens created after the change to be after 180 days (6 months) from creation.

alation_conf alation.authentication.token.refresh_token_lifespan -s 180

To change the Access Token refresh time, log in to the Alation server, and using alation_conf, update the APIAccessToken lifespan (in hours). For example, the following command sets the expiration time for any new APIAccessTokens created after the change to be after 2 hours from creation.

alation_conf alation.authentication.token.access_token_lifespan -s 2

Open API 3.0 Specification

The above APIs are also described using the Open API 3.0 Specification (OAS). OAS is
a broadly adopted industry standard for describing APIs.

To see the specification, replace {AlationInstanceURL} below with your Alation instance's URL and visit the link:

{AlationInstanceURL}/openapi/api_authentication/

NOTE:

1. The Swagger UI is not enabled by default on an Alation instance. Please set the flag
   alation.feature_flags.enable_swagger to True using alation_conf.
   

Create RefreshToken

Creates a new RefreshToken for the user.

URL

Data Parameters

Response Structure

Content-Type: text/json

Status: 201 CREATED

All Responses

Code Samples

cURL

BASE_URL="https://alation.yourcompany.com/integration/v1/createRefreshToken/"
USER_ID="[email protected]"
PASSWORD="secret"
NAME="My Precious"

# Create RefreshToken for user [email protected]
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE_URL}" --data-urlencode "username=${USER_ID}" --data-urlencode "password=${PASSWORD}" --data-urlencode "name=${NAME}" -v

Python

import requests

# Replace username, name and password with your login ID, desired token name and password.
data = {'username':'[email protected]', 'password':'secret', 'name': 'My Precious Token'}

ALATION_AT_YOUR_COMPANY_URL="https://alation.yourcompany.com"

# Create RefreshToken for user: [email protected]
response = requests.post(
    '{base_url}/integration/v1/createRefreshToken/'.format(base_url=ALATION_AT_YOUR_COMPANY_URL
), data=data)
print(response.text)
# Sample Response
# {
#     "user_id": 1151,
#     "created_at": "2020-07-15T16:08:09.673391-07:00",
#     "token_expires_at": "2020-09-13T16:08:09.672850-07:00",
#     "token_status": "ACTIVE",
#     "last_used_at": null,
#     "name": "My Precious Token",
#     "refresh_token": 
#       "mnuM-jp7uAOLWsG7ojs6rY-wweh2JVfKmNtWyPgVs-RdIysp4QyEHJtdd5Q5fECWEOsGVYxZ0eHy37j_lqoPcQ"
# }

Regenerate a RefreshToken

This API lets you to regenerate a RefreshToken, invalidating the current token passed in the
request body.

URL

Data Parameters

Response Structure

Content-Type: text/json

Status: 201 CREATED

Responses

Code Samples

cURL

BASE_URL="https://alation.yourcompany.com/integration/v1/regenRefreshToken/"
"REFRESH_TOKEN"= "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"USER_ID": 102

# Regenerate refresh_token
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE_URL}" --data "user_id=${USER_ID}&refresh_token=${REFRESH_TOKEN}" -v

Python

import requests

# Replace user_id and refresh_token with your user id and refresh_token
data = {
    "refresh_token": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
    "user_id": 102
}
ALATION_AT_YOUR_COMPANY_URL="https://alation.yourcompany.com"

# # Regenerate refresh_token
response = requests.post(
    '{base_url}/integration/v1/regenRefreshToken/'.format(base_url=ALATION_AT_YOUR_COMPANY_URL
), data=data)
print(response.text)
# Sample Response
# {
#     "user_id": 1151,
#     "created_at": "2020-07-15T16:08:09.673391-07:00",
#     "token_expires_at": "2020-09-13T16:08:09.672850-07:00",
#     "token_status": "ACTIVE",
#     "last_used_at": null,
#     "name": "My Precious Token",
#     "refresh_token": 
#       "mnuM-jp7uAOLWsG7ojs6rY-wweh2JVfKmNtWyPgVs-RdIysp4QyEHJtdd5Q5fECWEOsGVYxZ0eHy37j_lqoPcQ"
# }

Create APIAccessToken

Creates a new APIAccessToken. This API lets you to create a new APIAccessToken which can be
used for authenticating Alation public API requests.

NOTE: This would revoke any other active APIAccessToken (if present) created using
the RefreshToken in request body.

URL

Data Parameters

Response Structure

Content-Type: text/json

Status: 201 CREATED

All Responses

Code Samples

cURL

BASE_URL="https://alation.yourcompany.com/integration/v1/createAPIAccessToken/"
"REFRESH_TOKEN"= "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"USER_ID": 102

# Get APIAccessToken for user (102)
curl POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE_URL}" --data "user_id=${USER_ID}&refresh_token=${REFRESH_TOKEN}" -v

Python

import requests

# Replace user_id and refresh_token with your user id and refresh_token
data = {
    "refresh_token": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
    "user_id": 102
}
ALATION_AT_YOUR_COMPANY_URL="https://alation.yourcompany.com"

# Get APIAccessToken for user using the RefreshToken.
response = requests.post(
    '{base_url}/integration/v1/createAPIAccessToken/'.format(base_url=ALATION_AT_YOUR_COMPANY_URL
), data=data)
print(response.text)
# Sample Response 
# {
#     "user_id": 1151,
#     "created_at": "2020-07-15T16:32:34.793438-07:00",
#     "token_expires_at": "2020-07-16T16:32:34.789504-07:00",
#     "token_status": "ACTIVE",
#     "api_access_token": "GUAFqGbdD6eA_uwo6EO2Ntq_-KRMFVWgJ4jg2SBybGU"
# }

Revoke APIAccessToken

Revokes the active APIAccessToken created using the RefreshToken in the body.

URL

Data Parameters

Response Structure

Content-Type: text/json

Status: 201 CREATED

Responses

Code Samples

cURL

BASE_URL="https://alation.yourcompany.com/integration/v1/revokeAPIAccessTokens/"
"REFRESH_TOKEN"= "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"USER_ID": 102

# Revoke all the active APIAccessTokens associated with the given RefreshToken.
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE_URL}" --data "user_id=${USER_ID}&refresh_token=${REFRESH_TOKEN}" -v

Python

import requests

# Replace user_id and refresh_token with your user id and refresh_token
data = {
    "refresh_token": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
    "user_id": 102
}
ALATION_AT_YOUR_COMPANY_URL="https://alation.yourcompany.com"

# Revoke all active APIAccessTokens for the given refresh_token.
response = requests.post(
    '{base_url}/integration/v1/revokeAPIAccessTokens/'.format(
    base_url=ALATION_AT_YOUR_COMPANY_URL), data=data)
print(response.text)

Validate APIAccessToken

This API lets you to validate an API AccessToken, returning useful metadata about the token, if valid.

URL

Data Parameters

Response Structure

Content-Type: text/json

Status: 200 OK

Responses

Code Samples

cURL

BASE_URL="https://alation.yourcompany.com/integration/v1/validateAPIAccessToken/"
"API_ACCESS_TOKEN"= "VSp5oVbFx-Nk6aTd6Ot4H1Z1LaCIkpjv9_su-brvuC8",
"USER_ID": 102

# Get APIAccessToken for user (102)
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE_URL}" --data "user_id=${USER_ID}&api_access_token=${API_ACCESS_TOKEN}" -v

Python

import requests

# Replace user_id and refresh_token with your user id and refresh_token
data = {
    "api_access_token": "VSp5oVbFx-Nk6aTd6Ot4H1Z1LaCIkpjv9_su-brvuC8",
    "user_id": 102
}
ALATION_AT_YOUR_COMPANY_URL="https://alation.yourcompany.com"

# Validate APIAccessToken by passing it along in the request body.
response = requests.post(
    '{base_url}/integration/v1/validateAPIAccessToken/'.format(base_url=ALATION_AT_YOUR_COMPANY_URL
), data=data)
print(response.text)
# Sample Response 
# {
#     "user_id": 1151,
#     "created_at": "2020-07-15T16:32:34.793438-07:00",
#     "token_expires_at": "2020-07-16T16:32:34.789504-07:00",
#     "token_status": "ACTIVE",
#     "api_access_token": "GUAFqGbdD6eA_uwo6EO2Ntq_-KRMFVWgJ4jg2SBybGU"
# }

Validate RefreshToken

This API lets you validate an existing RefreshToken, returning useful metadata about the token, if valid.

URL

Data Parameters

Response Structure

Content-Type: text/json

Status: 200 OK

Responses

Code Samples

cURL

BASE_URL="https://alation.yourcompany.com/integration/v1/validateRefreshToken/"
"REFRESH_TOKEN"= "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"USER_ID": 102

# Validate the RefreshToken to see if it is still valid.
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE_URL}" --data "user_id=${USER_ID}&refresh_token=${REFRESH_TOKEN}" -v

Python

import requests

# Replace user_id and refresh_token with your user id and refresh_token
data = {
    "refresh_token": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
    "user_id": 102
}
ALATION_AT_YOUR_COMPANY_URL="https://alation.yourcompany.com"

# Validate the given RefreshToken.
response = requests.post(
    '{base_url}/integration/v1/validateRefreshToken/'.format(base_url=ALATION_AT_YOUR_COMPANY_URL
), data=data)
print(response.text)
# Sample Response
# {
#     "user_id": 1151,
#     "created_at": "2020-07-15T16:08:09.673391-07:00",
#     "token_expires_at": "2020-09-13T16:08:09.672850-07:00",
#     "token_status": "ACTIVE",
#     "last_used_at": null,
#     "name": "My Precious Token",
#     "refresh_token": 
#       "mnuM-jp7uAOLWsG7ojs6rY-wweh2JVfKmNtWyPgVs-RdIysp4QyEHJtdd5Q5fECWEOsGVYxZ0eHy37j_lqoPcQ"
# }

Videos

Token Authentication and Management APIs Tutorial (OAS/Swagger)

Token Authentication and Management APIs Tutorial (Alation GUI)