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.
(Optional) Enter a description, such as the token’s purpose or the name of an application that will use the token.
Click Generate Token.

Troubleshooting: You don’t have permission to generate a token for this role

When you click Generate Token, you can get an error message stating that You don’t have permission to generate a token for this role.

If you are certain that you have the necessary permissions, make sure the token description is less than 250 characters.
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, use GET /v2/organizations/roles.

Get the token from the response. clientId and secret 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, use GET /v2/organizations/roles.

Get the token from the response. clientId and secret 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_vert 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: Either tokens or clientIdSecrets, 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')