Refresh and Access Token Overview

Token Authentication and Management APIs

Public APIs for managing RefreshTokens and APIAccessTokens for the user.

Description

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

Remember

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

Login to the server, and using `conf`, update the

RefreshToken lifespan (in days),

conf 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 server, and using `conf`, update the

APIAccessToken lifespan (in hours),

conf 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 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 {InstanceURL} below with your instance's URL and visit the link:

{InstanceURL}/openapi/api_authentication/

Create RefreshToken

Creates a new RefreshToken for the user.

URL

POST /integration/v1/createRefreshToken/

Data Parameters

Name Type Description Required
username string

Username of the user.

Example: "basava@on.com"

Yes
password string

Password associated with the user.

Example: "P@s$w0rd!"

 Yes
name string

Create the RefreshToken with this name.

Example: "TableauRefreshToken"

Yes

Response Structure

Content-Type: text/json

Status: 201 CREATED

Name Type Description
refresh_token string

RefreshToken generated for the user.

Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"

user_id integer

User ID associated with the refresh token who generated this token.

Example: 102

created_at dateTime Timezone aware date-time at which the refresh token is created at.
name string

Name of the RefreshToken.

Example: "TableauRefreshToken"

token_expires_at dateTime Timezone aware date-time until which the RefreshToken is valid for.
token_status string

Current status of the RefreshToken.

Enum:

"active",

"expired",

"revoked"

Example: "active"

All Responses

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

Code Samples

cURL

BASE_URL="https://yourcompany.com/integration/v1/createRefreshToken/"

USER_ID="dave@example.com"

PASSWORD="secret"

NAME="My Precious"

# Create RefreshToken for user dave@example.com

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':'dave@example.com', 'password':'secret', 'name': 'My Precious Token'}

AT_YOUR_COMPANY_URL="https://yourcompany.com"

# Create RefreshToken for user: dave@example.com

response = requests.post(

'{base_url}/integration/v1/createRefreshToken/'.format(base_url=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"

# }

census