Manage application tokens
Use application tokens to authenticate and connect to your databases programmatically, either directly or through your apps.
To manage application tokens, you must have the Organization Administrator or Database Administrator role.
Token roles
Every token is assigned a role. The role determines the level of access an application has to Astra DB resources.
Once you create a token, you can’t change the token’s assigned role. However, if a token has a custom role, any future changes to that custom role’s permissions also apply to the token. This includes custom roles that you create as well as custom roles that Astra DB creates when you generate an application token for a database.
Consider the following when choosing a role for a token:
-
You can limit custom roles to specific databases, keyspaces, and tables. In contrast, default roles include all current and future databases, keyspaces, and tables in your organization.
When you add new databases, keyspaces, and tables, you might need to modify your custom roles to include those new resources, if necessary. If you use the DevOps API to manage custom roles, you can create wildcard (
*
) scopes that account for future instances of these resources. -
Custom roles are useful if you aren’t sure which permissions a token needs. You can use a custom role to test, modify, and retest until you determine the necessary permissions.
-
Whereas default roles are immutable, custom roles can be edited. This poses a risk of the role’s permissions being modified without realizing the implication to any tokens with that role. This could include granting excess permissions or revoking necessary permissions. Administrators can mitigate this risk by observing industry best practices for RBAC, such as the principle of least privilege, regular permissions auditing, and using meaningful names to clearly describe a custom role’s purpose or permissions.
For more information, see Manage roles and permissions.
Generate an application token for a database
You can generate an application token with the Database Administrator role for a specific database.
Use this approach to create narrowly-scoped tokens that you can only use for one database. To create broadly-scoped tokens or tokens with other roles, see Generate an application token with any role.
-
Serverless (Vector) database
-
Serverless (Non-Vector) database
-
In the Astra Portal navigation menu, select your Serverless (Vector) database.
-
On the Overview tab, in the Database Details section, click Generate Token.
In Database Details, you can find your database’s API endpoint to use with the Data API. The database API endpoint format is
https://ASTRA_DB_ID-ASTRA_DB_REGION.apps.astra.datastax.com
. -
Copy the token and store it securely. The Astra Portal shows the token only once.
When you create an application token from a database’s Overview tab, Astra DB automatically creates a custom role based on the Database Administrator default role that is scoped to that database.
These custom roles are named DATABASE_NAME Database Administrator
, and you can edit them like any other custom role.
-
In the Astra Portal navigation menu, select your Serverless (Non-Vector) database.
-
On the Connect tab, in the Database Essentials section, click Generate Database Token.
-
Copy or download the token details and store them securely. The Astra Portal shows the token details only once.
Generate an application token with any role
You can generate application tokens with any role. Tokens with broad roles, such as the Organization Administrator role, can be valid for multiple databases or administrative operations.
-
Astra Portal
-
DevOps API
-
In the Astra Portal navigation menu, click Tokens.
-
In the Generate New Token section, select a default or custom role to assign to the token.
Select a role to see the associated permissions. For more information, see Token roles.
-
Click Generate Token.
-
Copy or download the Application Token Details and store them securely. The Astra Portal shows the token details only once.
-
Tokens v1
-
Tokens v2
-
To generate a token, use
POST /v2/clientIdSecrets
:curl -sS --location -X POST "https://api.astra.datastax.com/v2/clientIdSecrets" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "roles": [ "ROLE_ID", "ROLE_ID" ] }'
Replace the following:
-
APPLICATION_TOKEN
: An application token with the Organization Administrator role. Create this initial token in the Astra Portal, and then use it to create tokens with the DevOps API. -
ROLE_ID
: An array of one or more roles to assign to the token. To get role IDs, useGET /v2/organizations/roles
.
-
-
Get the
token
from the response.clientId
andsecret
are legacy authentication methods.{ "clientId":"zjCEYwRGWocLfQJHBNQxvorr", "secret":"SLR...", "orgId":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510", "roles":[ "21ef3576-0197-415a-b167-d510af12ecf0" ], "token":"AstraCS:...", "generatedOn":"2021-04-30T19:38:26.147847107Z" }
-
To generate a token, use
POST /v2/tokens
:curl -sS --location -X POST "https://api.astra.datastax.com/v2/tokens" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "roles": [ "ROLE_ID", "ROLE_ID" ] }'
Replace the following:
-
APPLICATION_TOKEN
: An application token with the Organization Administrator role. Create this initial token in the Astra Portal, and then use it to create tokens with the DevOps API. -
ROLE_ID
: An array of one or more roles to assign to the token. To get role IDs, useGET /v2/organizations/roles
.
-
-
Get the
token
from the response.clientId
andsecret
are legacy authentication methods.{ "clientId": "zjCEYwRGWocLfQJHBNQxvorr", "secret": "SLR...", "orgId": "dccb8c32-cc2a-4bea-bd95-47ab8eb20510", "roles": [ "21ef3576-0197-415a-b167-d510af12ecf0" ], "token": "AstraCS:...", "generatedOn": "2021-04-30T19:38:26.147847107Z", }
Get a list of tokens
-
Astra Portal
-
DevOps API
-
In the Astra Portal navigation menu, click Tokens.
The Manage Existing Tokens section lists the application tokens in the selected organization.
To get a list of tokens in your organization, you can use either GET /v2/clientIdSecrets
or GET /v2/tokens
.
Both requests return the same information.
curl -sS --location -X GET "https://api.astra.datastax.com/v2/clientIdSecrets" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
Replace APPLICATION_TOKEN
with an application token that has the Organization Administrator role.
Response
A successful response returns an array of client
objects, where each clientId
represents a token identifier.
The response includes the roles assigned to each token, but the secret
and token
values are excluded.
{
"clients": [
{
"clientId":"DkFtHKMhDQDuQtlExkSzwbya",
"roles":[ "21ef3576-0197-415a-b167-d510af12ecf0" ],
"generatedOn":"2021-02-22T17:09:58.668Z"
},
{
"clientId":"eYSboCJaESiblJZnKZWMxROv",
"roles":[ "21ef3576-0197-415a-b167-d510af12ecf0" ],
"generatedOn":"2021-04-28T18:49:11.323Z"
}
]
}
Delete an application token
Application tokens never expire. |
As a best practice, rotate or revoke unused and potentially compromised tokens.
-
Astra Portal
-
DevOps API
-
In the Astra Portal navigation menu, click Tokens.
-
In the Manage Existing Tokens section, find the application token that you want to delete, click
More, and then select Delete. -
In the confirmation dialog, click Delete Token.
-
If you need to rotate tokens, generate a token to replace the one that you just deleted.
To delete a token, you can use either DELETE /v2/clientIdSecrets
or DELETE /v2/tokens
:
curl -sS --location -X DELETE "https://api.astra.datastax.com/v2/ENDPOINT/CLIENT_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
Replace the following:
-
ENDPOINT
: Eithertokens
orclientIdSecrets
, depending on the endpoint you want to use. -
CLIENT_ID
: The client ID of the token that you want to delete. To get a token’s client ID, see Get a list of tokens. -
APPLICATION_TOKEN
: An application token with the Organization Administrator role.
Token details
Token details include the clientId
, secret
, and token
.
The clientId
and secret
are legacy authentication methods.
The token
, in the format AstraCS:…
, comprises everything you need for Astra DB token authentication.
In some cases, such as with DataStax drivers or certain integrations, you might need to provide authentication in the form of a username and password.
Unless otherwise noted, you can set the username
to the literal string token
, and the password or secret to your application token.
-
Username and token
-
clientId and secret (legacy)
auth_provider = PlainTextAuthProvider("token", "AstraCS:...")
auth_provider = PlainTextAuthProvider('clientId', 'clientSecret')