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, built-in 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 built-in 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 Roles and permissions reference.

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 Cassandra driver connections that read and write to your database.
Generate an application token scoped to an organization: Generate tokens with any custom or built-in 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.

In the Astra Portal, click Managed clusters, and then click the name of the database that you want to connect to.
Click More, and then select Generate 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.

Use the Astra Portal

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, make sure the enterprise/organization filter is set to the organization that you want to manage.

If the organization belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Tokens.
In the Generate New Token section, select a 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 of the token to help you identify its purpose.

You cannot edit the description after generating the token.
To set a lifetime for the token, edit the Expiration field.

The default lifetime is Never expire.
Click Generate Token, copy or download the token (AstraCS:…), and then store it securely. The Astra Portal shows the token details only once.

Use the DevOps API

To generate a token for an organization, you can use either POST /v2/tokens or POST /v2/clientIdSecrets:
/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" ],
  "tokenExpiry": "EXPIRATION",
  "description": "DESCRIPTION"
}'
```
/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" ],
  "tokenExpiry": "EXPIRATION",
  "description": "DESCRIPTION"
}'
```
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.
- EXPIRATION: An optional date and time when the token expires, in ISO 8601 format, such as 2025-01-01T21:29:00Z. If omitted, the token never expires.
- DESCRIPTION: An optional description of the token to help you identify its purpose.
The /v2/tokens endpoint also accepts an optional orgId field, but it is only relevant when creating an organization token with an enterprise application token.

Get the token value from the response. The clientId and secret fields 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.

Don’t use enterprise application tokens for application development. They are designed for enterprise organization management tasks, not for database-level access. Instead, 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 Read Enterprise Token and Write Enterprise Token permissions, such as the Enterprise Administrator role.

Use the Astra Portal

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to 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 of the token to help you identify its purpose.

You cannot edit the description after generating the token.
To set a lifetime for the token, edit the Expiration field.

The default lifetime is Never expire.
Click Generate Token, copy the token (AstraCS:…), and then store it securely.

The Astra Portal shows the token only once.

Use the DevOps API `/v2/tokens` endpoint

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" ],
  "tokenExpiry": "EXPIRATION",
  "description": "DESCRIPTION"
}'
```
Replace the following:
- ENTERPRISE_APPLICATION_TOKEN: An enterprise application token with the Read Enterprise Token and Write Enterprise Token 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.
- EXPIRATION: An optional date and time when the token expires, in ISO 8601 format, such as 2025-01-01T21:29:00Z. If omitted, the token never expires.
- DESCRIPTION: An optional description of the token to help you identify its purpose.

Get the token value 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 generate a token scoped to an organization

To programmatically generate an application token for an organization in your enterprise, use POST /v2/tokens with the additional orgId parameter:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/tokens" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORGANIZATION_ID",
  "roles": [ "ROLE_ID", "ROLE_ID" ],
  "tokenExpiry": "EXPIRATION",
  "description": "DESCRIPTION"
}'
```
Replace the following:
- APPLICATION_TOKEN: An enterprise application token with a role that is permitted to create tokens in the enterprise.
- ORGANIZATION_ID: The organization ID for the organization where you want to create the token. The specified organization must belong to the enterprise.
- ROLE_ID: An array of one or more roles to assign to the token.
  
  You must specify roles that are available in the specified organization. You cannot assign roles from the enterprise or other organizations.
  
  To get role IDs, use GET /v2/organizations/roles. The roles returned by this request depend on the scope of the provided application token. If you call this endpoint with an enterprise application token, it returns only enterprise-level roles. To get an organization’s roles, you must use an organization application token.
- EXPIRATION: An optional date and time when the token expires, in ISO 8601 format, such as 2025-01-01T21:29:00Z. If omitted, the token never expires.
- DESCRIPTION: An optional description of the token to help you identify its purpose.

Get the token value 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

You can view tokens in the Astra Portal, or you can retrieve them programmatically with the DevOps API.

View tokens in the Astra Portal

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to the enterprise or organization that you want to manage.

To view an organization that belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Tokens.

The Manage existing tokens section lists the tokens associated with the selected organization or enterprise.

Get tokens with the DevOps API

To get a list of tokens in an organization or enterprise, use GET /v2/tokens:

/v2/tokens

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

The returned tokens are determined by the scope of the provided APPLICATION_TOKEN:

To retrieve tokens in an organization, provide an application token with the Organization Administrator role or a custom role with permission to read tokens.
To retrieve tokens in an enterprise, provide an enterprise application token with the Enterprise Administrator role or a custom role with the Read Enterprise Token permission.

A successful request 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"
    }
  ]
}

For organization-scoped tokens only, you can also use GET /v2/clientIdSecrets. This request returns the same information as GET /v2/tokens, but it cannot retrieve enterprise application tokens.

/v2/clientIdSecrets

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

Delete an application token

Application tokens never expire.

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

Revoke tokens in the Astra Portal

To revoke tokens in the Astra Portal, you must go to the Tokens page for the relevant organization or enterprise, depending on the token’s scope:

Revoke organization and database tokens

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to the organization that you want to manage.

If the organization belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Tokens.
In the Manage existing tokens section, find 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.

Revoke enterprise tokens

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to your enterprise.
In the Settings navigation menu, click Tokens.
In the Manage existing tokens section, find 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 tokens with the DevOps API

To delete token in an organization or enterprise, use DELETE /v2/tokens:

/v2/tokens

curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/tokens/CLIENT_ID" \
--header "Authorization: Bearer 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.
APPLICATION_TOKEN: An application token scoped to the same organization or enterprise as the token that you want to delete:
- To delete a token in an organization, provide an application token with the Organization Administrator role.
- To delete a token in an enterprise, provide an enterprise application token with the Enterprise Administrator role.

For organization-scoped tokens only, you can also use DELETE /v2/clientIdSecrets. This request has the same functionality as DELETE /v2/tokens, but it cannot delete enterprise application tokens.

/v2/clientIdSecrets

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

Token details and authentication methods

Token details include the clientId, secret, and token. The clientId and secret are legacy authentication methods. The token, prefixed by AstraCS:, is a unified token that comprises everything you need for Astra token authentication.

If token-only authentication is supported, such as with the DevOps API, then you only need the unified application token (AstraCS:…).

If username and password authentication is required, such as with Cassandra drivers and the standalone CQL shell, you still only need the unified application token. In this case, set the username to the literal string token, and set the password or secret to your unified application token. For example:

Example: Modern username and password authentication

auth_provider = PlainTextAuthProvider("token", "AstraCS:...")

For older databases using a long-lived legacy token without the unified token, you can pass the clientId and secret as the username and password:

Example: Legacy clientId and secret authentication

auth_provider = PlainTextAuthProvider('clientId', 'clientSecret')

If you are using a legacy token created prior to the introduction of the unified token format, DataStax recommends rotating these tokens due to their age.

Manage application tokens

Application token roles

Generate application tokens

Generate an application token scoped to a database

Generate an application token scoped to an organization

Use the Astra Portal

Use the DevOps API

Generate an application token scoped to an enterprise

Use the Astra Portal

Use the DevOps API `/v2/tokens` endpoint

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

Get a list of tokens

View tokens in the Astra Portal

Get tokens with the DevOps API

Delete an application token

Revoke tokens in the Astra Portal

Revoke tokens with the DevOps API

Token details and authentication methods

See also

Was this helpful?

Give Feedback