Refresh & Access Token Overview

Token Authentication and Management APIs

Public APIs for managing RefreshTokens and APIAccessTokens for the user.

NOTE: If your Organization is using SSO, like Okta, LDAP, and 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.

NOTE:

  • 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.
    e.g.:
      Login to the alation server, and using `alation_conf`, update the
    
    RefreshToken lifespan (in days),
    alation_conf alation.authentication.token.refresh_token_lifespan -s 180
    -- sets the expiration time for any new RefreshTokens created after
    the change to be after 180 days(6 months) from creation.
      Login to the alation server, and using `alation_conf`, update the
       APIAccessToken lifespan (in hours),
    
    alation_conf alation.authentication.token.access_token_lifespan -s 2
    -- sets the expiration time for any new APIAccessTokens created after
    the change to be after 2 hours from creation.
  • All these APIs, except Create RefreshToken, are
    supported in SAML 2.0 Single Sign On environments. If you're using the SAML
    authentication, you can create the refresh tokens using the Alation GUI by
    visiting <BASE_URL>/account/auth page.

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

POST /integration/v1/createRefreshToken/

Data Parameters

NameTypeDescriptionRequired
usernamestringUsername of the user on Alation.
Example: "[email protected]"
Yes
passwordstringPassword associated with the user on Alation.
Example: "[email protected]$w0rd!"
Yes
namestringCreate the RefreshToken with this name.
Example: "TableauRefreshToken"
Yes

Response Structure

Content-Type: text/json

Status: 201 CREATED

NameTypeDescription
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
user_idintegerUser ID associated with the refresh token who generated this token on Alation.
Example: 102
created_atdateTimeTimezone aware date-time at which the refresh token is created at.
namestringName of the RefreshToken.
Example: "TableauRefreshToken"
token_expires_atdateTimeTimezone aware date-time until which the RefreshToken is valid for.
token_statusstringCurrent status of the RefreshToken.
Enum:"active", "expired", "revoked"
Example: "active"

All Responses

CodeDescription
201Created
400Malformed Request
401Unauthorized bad/missing token
403Forbidden User cannot edit this resource
404The specified resource was not found
500Internal Server Error

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

POST /integration/v1/regenRefreshToken/

Data Parameters

NameTypeDescriptionRequired
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
Yes
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
Yes

Response Structure

Content-Type: text/json

Status: 201 CREATED

NameTypeDescription
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
created_atdateTimeTimezone aware date-time at which the RefreshToken is created at.
namestringName of the RefreshToken.
Example: "TableauRefreshToken"
token_expires_atdateTimeTimezone aware date-time until which the RefreshToken is valid for.
token_statusstringCurrent status of the RefreshToken.
Enum:"active", "expired", "revoked"
Example: "active"
Responses
CodeDescription
201Created
400Malformed Request
401Unauthorized bad/missing token
403Forbidden User cannot edit this resource
404The specified resource was not found
500Internal Server Error

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

POST /integration/v1/createAPIAccessToken/

Data Parameters

NameTypeDescriptionRequired
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
Yes
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
Yes

Response Structure

Content-Type: text/json

Status: 201 CREATED

NameTypeDescription
api_access_tokenstringAPIAccessToken that can be used as token header for authenticating public API requests to Alation Server.
Example: "e25388fde8290dc286a6164fa2d97e551b53498dcbf7bc378eb1f178"
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
created_atdateTimeTimezone aware date-time at which the APIAccessToken is created at.
token_expires_atdateTimeTimezone aware date-time until which the APIAccessToken is valid for.
token_statusstringCurrent status of the APIAccessToken.
Enum:"active", "expired", "revoked"
Example: "active"

All Responses

CodeDescription
201Created
400Malformed Request
401Unauthorized bad/missing token
403Forbidden User cannot edit this resource
404The specified resource was not found
500Internal Server Error

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

POST /integration/v1/revokeAPIAccessTokens/

Data Parameters

NameTypeDescriptionRequired
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
Yes
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
Yes

Response Structure

Content-Type: text/json

Status: 201 CREATED

NameTypeDescription
detailstringSuccess Message after revoking the tokens.
Example: "Revoked active access tokens for user: '10'"
Responses
CodeDescription
200OK
400Malformed Request
401Unauthorized bad/missing token
403Forbidden User cannot edit this resource
404The specified resource was not found
500Internal Server Error

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

POST /integration/v1/validateAPIAccessToken/

Data Parameters

NameTypeDescriptionRequired
api_access_tokenstringAPIAccessToken that can be used as token header for authenticating public API requests to Alation Server.
Example: "e25388fde8290dc286a6164fa2d97e551b53498dcbf7bc378eb1f178"
Yes
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
Yes

Response Structure

Content-Type: text/json

Status: 200 OK

NameTypeDescriptionRequired
api_access_tokenstringAPIAccessToken that can be used as token header for authenticating public API requests to Alation Server.
Example: "e25388fde8290dc286a6164fa2d97e551b53498dcbf7bc378eb1f178"
No
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
No
created_atdateTimeTimezone aware date-time at which the APIAccessToken is created at.No
token_expires_atdateTimeTimezone aware date-time until which the APIAccessToken is valid for.No
token_statusstringCurrent status of the APIAccessToken.
Enum:"active", "expired", "revoked"
Example: "active"
No
Responses
CodeDescription
200OK
400Malformed Request
401Unauthorized bad/missing token
403Forbidden User cannot edit this resource
404The specified resource was not found
500Internal Server Error

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

POST /integration/v1/validateRefreshToken/

Data Parameters

NameTypeDescriptionRequired
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
Yes
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
Yes

Response Structure

Content-Type: text/json

Status: 200 OK

NameTypeDescription
refresh_tokenstringRefreshToken generated for the user in Alation.
Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
user_idintegerUser ID associated with the RefreshToken who generated this token on Alation.
Example: 102
created_atdateTimeTimezone aware date-time at which the RefreshToken is created at.
namestringName of the RefreshToken.
Example: "TableauRefreshToken"
token_expires_atdateTimeTimezone aware date-time until which the RefreshToken is valid for.
token_statusstringCurrent status of the RefreshToken.
Enum:"active", "expired", "revoked"
Example: "active"
Responses
CodeDescription
200OK
400Malformed Request
401Unauthorized bad/missing token
403Forbidden User cannot edit this resource
404The specified resource was not found
500Internal Server Error

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)