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.

Application token roles

Every token is assigned a role. The role determines the level of access an application has to Astra resources.

Once you create a token, you cannot 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 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 application tokens

Application tokens have specific organization and role scopes.

When you create a token, you select one or more roles to assign to the token. These roles determine the token’s permissions and the actions that the token is authorized to take.

The role also determines the hierarchical scope of the token. For example, if you create a token with the Organization Administrator role, the token has full access to the entire organization and all resources within that organization, including databases, users, billing, and security configurations.

For more information, see the following:

Generate an application token scoped to a database: Generate an application token that is scoped to a single database.

This token is ready to use for application development. For example, you can use it to authorize Data API commands that read and write to your database.
Generate an application token scoped to an organization: Generate tokens with any custom or default role in an organization.

If you have narrowly-scoped custom roles restricted to specific keyspaces or tables, use this option to generate tokens with those custom roles.
Generate an application token scoped to an enterprise: Generate tokens for enterprise organization management with access to multiple organizations.

Generate an application token scoped to a database

When viewing a database in the Astra Portal, you can generate a token that is scoped to a single database.

With one click, Astra creates a custom Database Administrator role scoped to the current database, and then generates an application token with the new custom role.

These custom roles have the same permissions as the Database Administrator role, but they are limited to one database. These roles are named DATABASE_NAME Database Administrator, and you can edit them like any other custom role.

Serverless (Vector) database
Serverless (Non-Vector) database

In the Astra Portal navigation menu, click Databases, and then click the name of 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.

In the Astra Portal navigation menu, click Databases, and then click the name of 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 scoped to an organization

You can generate application tokens with any role that is available to your Astra organization.

Tokens with broad roles, such as the Organization Administrator role, can be valid for multiple databases or administrative operations.

Astra Portal
DevOps API

To create tokens in the Astra Portal, you must have a user role with permission to create tokens.

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the active organization, and then select the organization where you want to create a token.

If the organization belongs to an enterprise, select the enterprise, and then select the organization in the Organizations list.
In the Settings 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 Application token roles.
Optional: Enter a description, such as the token’s purpose or the name of an application that will use the token.

You cannot edit the description after generating the token.
Click Generate Token.
Copy or download the Application Token Details and store them securely. The Astra Portal shows the token details only once.

There are two DevOps API endpoints that can generate tokens.

For general information about using the DevOps API, see Get started with the Astra DevOps API.

Tokens v1
Tokens v2

To generate a token, use POST /v2/clientIdSecrets:
```
curl -sS -L -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 a user role that has permission to create tokens, such as the Organization Administrator role.
  
  You must create an organization’s first token in the Astra Portal. Then, you can use that token to create additional tokens programmatically.
- 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 -L -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 a user role that has permission to create tokens, such as the Organization Administrator role.
  
  You must create an organization’s first token in the Astra Portal. Then, you can use that token to create additional tokens programmatically.
- 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",
}

Generate an application token scoped to an enterprise

Enterprise application tokens are application tokens with enterprise roles. You use them to authenticate DevOps API operations related to enterprise organization management.

Due to their expansive permissions, DataStax doesn’t recommend using enterprise application tokens for application development. For example, if an application needs to read or write to a database, use an application token with a narrower scope, such as the Database Administrator role.

To generate enterprise application tokens, you must have a role with the ent-token-read and ent-token-write permissions, such as the Enterprise Administrator role.

Astra Portal
DevOps API

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the active organization or enterprise, and then select your enterprise.
In the Settings navigation menu, click Tokens.
In the Generate new token section, select an enterprise role for the token.
Optional: Enter a description, such as the purpose of the token or the name of an application that will use the token.

You cannot change the description after generating the token.
Click Generate Token.
Copy the token and store it securely.

To programmatically generate an enterprise application token, use POST /v2/tokens:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/tokens" \
--header "Authorization: Bearer ENTERPRISE_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "roles": [ "ROLE_ID", "ROLE_ID" ]
}'
```
Replace the following:
- ENTERPRISE_APPLICATION_TOKEN: An enterprise application token with the ent-token-read and ent-token-write permissions. You can create an initial token in the Astra Portal, and then use that token to create additional tokens with the DevOps API.
- ROLE_ID: An array of one or more enterprise roles to assign to the token.
  
  To get enterprise role IDs, use GET /v2/organizations/roles. The roles returned by this request depend on the scope of the provided application token. To retrieve enterprise roles, your application token must have the Enterprise Administrator role.

Get the token from the response:

{
  "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",
}

Use an enterprise application token to create a token scoped to an organization

To programmatically generate an application token for an organization in your enterprise, use POST /v2/tokens:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/tokens" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORG_ID",
  "roles": [ "ROLE_ID", "ROLE_ID" ]
}'
```
Replace the following:
- APPLICATION_TOKEN: An enterprise application token.
- ORG_ID: The organization ID for the organization where you want to create the token. The authorization token must have permission to create tokens in the specified organization.
- ROLE_ID: An array of one or more roles to assign to the token. Make sure that you select roles that are available in the specified organization.
  
  To get role IDs, use GET /v2/organizations/roles. The roles returned by this request depend on the scope of the provided application token. Enterprise application tokens are limited to enterprise roles. To get an organization’s roles, you must use an organization application token.

Get the token from the response:

{
  "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

Get organization and database tokens
Get enterprise tokens

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the active organization, and then select the organization where you want to view tokens.

If the organization belongs to an enterprise, select the enterprise, and then select the organization in the Organizations list.
In the Settings navigation menu, click Tokens.

The Manage Existing Tokens section lists the application tokens in the selected organization.

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the active organization or enterprise, and then select your enterprise.
In the Settings navigation menu, click Tokens.

The Manage existing tokens section lists the enterprise application tokens.

Get organization and database tokens
Get enterprise tokens

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 -L -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.

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"
    }
  ]
}

Create an enterprise application token that has a role with the ent-token-read permission.

Use GET /v2/tokens to get a list of enterprise application tokens:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/tokens" \
--header "Authorization: Bearer ENTERPRISE_APPLICATION_TOKEN" \
--header "Content-Type: application/json"

{
  "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"
    }
  ]
}

For more information about using the DevOps API, see Get started with the Astra DevOps API.

Delete an application token

Application tokens never expire.

As a best practice, revoke and rotate unused or potentially compromised tokens.

Astra Portal
DevOps API

Revoke organization and database tokens
Revoke enterprise tokens

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the active organization, and then select the organization where you want to delete a token.

If the organization belongs to an enterprise, select the enterprise, and then select the organization in the Organizations list.
In the Settings navigation menu, click Tokens.
In the Manage existing tokens section, locate the token 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 new token to replace the one that you just deleted.

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the active organization or enterprise, and then select your enterprise.
In the Settings navigation menu, click Tokens.
In the Manage existing tokens section, locate the token you want to delete, and then click Delete.
If you need to rotate tokens, generate a new token to replace the one that you just deleted.

Revoke organization and database tokens
Revoke enterprise tokens

To delete a token, you can use either DELETE /v2/clientIdSecrets or DELETE /v2/tokens:

curl -sS -L -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.

To delete a token, use DELETE /v2/tokens:

curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/tokens/CLIENT_ID" \
--header "Authorization: Bearer ENTERPRISE_APPLICATION_TOKEN" \
--header "Content-Type: application/json"

Replace the following:

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.
ENTERPRISE_APPLICATION_TOKEN: An enterprise application token.

For more information about using the DevOps API, see Get started with the Astra DevOps API.

Use the Astra HashiCorp Vault plugin

The Astra plugin for HashiCorp Vault is an open-source project that adds dynamic lifecycle management features for Astra application tokens.

What is HashiCorp Vault?

HashiCorp Vault is an identity-based secrets and encryption management system that provides key-value encryption services gated by authentication and authorization methods.

HashiCorp Vault provides secure storage, management, auditing, and access controls for tokens, secrets, and other sensitive data.

HashiCorp Vault is extensible through various interfaces, which allows plugins, including the Astra plugin, to contribute to this ecosystem.

Due to the Astra object hierarchy, application tokens aren’t associated with specific users, and they don’t have robust metadata.

With the Astra plugin for HashiCorp Vault, you can create and manage dynamic tokens outside of the Astra Portal, and then use them in your client applications to access your Astra databases and organizations.

Authorized Vault administrators can use vault commands to do the following:

Rotate tokens based on a token’s lifetime lease
Define a default lease time
Create new tokens with lease settings
List tokens by Client ID
View lease details
List all leases
Renew a token or lease before the lease expires
Specify a lease duration during renewal
Delete a token
Attach token creator metadata to tokens
Attach intended usage metadata to tokens

To configure and use the plugin, go to the GitHub repository for the Astra plugin for HashiCorp Vault.

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 token authentication.

In some cases, such as with 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')