Manage roles and permissions

Astra uses role-based access control (RBAC) to manage the levels of access that users and applications have to your databases and organizations.

Roles define the level of access that an entity has to your organization and databases. You can assign roles to users and application tokens. Your apps can use application tokens to access your Astra resources based on the roles assigned to the tokens.

You can use built-in default roles and create custom roles. All roles have a set of permissions and resource scopes.

When you create and apply roles, consider your organization’s security policies and industry best practices for RBAC, such as the principle of least privilege.

Default roles

Astra provides built-in default roles that you can assign to users and application tokens. These roles are designed to cover the most common use cases for organization administration, accessing databases, and interacting with other Astra resources.

Default roles have access to resources in your entire organization, including all databases. If you assign a default role to an application token, then any application using that token can perform the actions permitted by that role on any of your databases. To limit access to specific databases or keyspaces, you must create a custom role with limited scope.

You can’t edit or delete default roles.

Default Astra roles
Role name	Role permissions
Enterprise Administrator	Expand to see role permissions Enterprise permissions Read Enterprise Billing Write Enterprise Billing Read Enterprise User Write Enterprise User Read Enterprise Token Write Enterprise Token Manage Enterprise Organization Read Enterprise Role Write Enterprise Role
Enterprise Billing Administrator	Expand to see role permissions Enterprise permissions Read Enterprise Billing Write Enterprise Billing Read Enterprise User Write Enterprise User Read Enterprise Token Write Enterprise Token Manage Enterprise Organization Read Enterprise Role Write Enterprise Role
Enterprise Organization Administrator	Expand to see role permissions Enterprise permissions Read Enterprise Billing Write Enterprise Billing Read Enterprise User Write Enterprise User Read Enterprise Token Write Enterprise Token Manage Enterprise Organization Read Enterprise Role Write Enterprise Role
Organization Administrator	Grants all organization, keyspace, table, and API access permissions within the scope of one organization. Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Administrator Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Administrator User	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Billing Administrator	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
UI View Only	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Database Administrator	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Read Only Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Read/Write Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Read Only User	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
Read/Write User	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
API Administrator Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
API Read/Write Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
API Read Only Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
API Read Only User	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
API Administrator User	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST
API Read/Write User	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Migrator Proxy Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read IP Access List Read Organization Read Token Read User Terminate DB View DB Write Billing Write CMK Key Write Custom Role Write External Auth Write IP Access List Write Organization Write Token Write User Reset Password Suspend DB Keyspace permissions Alter Keyspace Authorize Keyspace Create All Keyspaces Create Keyspace Describe All Keyspaces Describe Keyspace Drop Keyspace Grant Keyspace Modify Keyspace Table permissions Alter Table Authorize Table Create Table Describe Table Drop Table Grant Table Modify Table Select Table API access permissions Access CQL Access GraphQL Access REST

Custom roles

Use custom roles to tailor granular permissions for your teams and applications. For example, you could create one custom role with access to a few databases and another custom role with access to specific keyspaces in one database only.

To manage custom roles for an organization, you must have a role with the Read Custom Role, Write Custom Role, and Delete Custom Role permissions, such as the Organization Administrator role.

To manage custom roles for an enterprise, you must have a role with the Read Enterprise Role and Write Enterprise Role permissions, such as the Enterprise Administrator role.

View roles

Before creating custom roles, inspect the existing custom roles to avoid duplicating roles.

Custom roles named DATABASE_NAME Database Administrator are automatically generated when you create an application token scoped to a database, and you can edit them like any other custom role.

Astra Portal
DevOps API

View custom organization roles
View custom enterprise roles

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 custom roles.

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

The Roles management page includes all custom roles in the 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 Roles.

The Role management page lists all custom enterprise roles.

Use GET /v2/organizations/roles to get information about all default and custom roles in an organization:

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

For each role, the response includes the id, name, policy, and last_update metadata. The policy object includes the following:

description: The role name.
resources: An array of resource IDs that define the role’s access to Astra resources. For more information, see Resource scopes.
actions: The permissions granted to the role.
effect: Indicates that the role grants access to the named resources and permissions. This is always allow.

Result

[
  {
    "id": "ad0566b5-2a67-49de-89e8-92258c2f2c98",
    "name": "Organization Administrator",
    "policy": {
      "description": "Organization Administrator",
      "resources": [
        "drn:astra:org:__ORG_ID__",
        "drn:astra:org:__ORG_ID__:db:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*",
        "drn:astra:org:__ORG_ID__:stream:*",
        "drn:astra:org:__ORG_ID__:role:*"
      ],
      "actions": [
        "accesslist-read",
        "accesslist-write",
        "org-read",
        "org-write",
        "org-audits-read",
        "org-cmk-read",
        "org-cmk-write",
        "org-role-read",
        "org-role-write",
        "org-role-delete",
        "org-external-auth-read",
        "org-external-auth-write",
        "org-notification-write",
        "org-token-read",
        "org-token-write",
        "org-billing-read",
        "org-billing-write",
        "org-user-read",
        "org-user-write",
        "org-db-create",
        "org-db-passwordreset",
        "org-db-terminate",
        "org-db-suspend",
        "org-db-addpeering",
        "org-db-managemigratorproxy",
        "org-db-expand",
        "org-db-view",
        "org-integrations-read",
        "org-integrations-write",
        "org-stream-manage",
        "db-manage-privateendpoint",
        "db-all-keyspace-create",
        "db-all-keyspace-describe",
        "db-keyspace-grant",
        "db-keyspace-modify",
        "db-keyspace-describe",
        "db-keyspace-create",
        "db-keyspace-authorize",
        "db-keyspace-alter",
        "db-keyspace-drop",
        "db-manage-region",
        "db-table-select",
        "db-table-grant",
        "db-table-modify",
        "db-table-describe",
        "db-table-create",
        "db-table-authorize",
        "db-table-alter",
        "db-table-drop",
        "db-graphql",
        "db-rest",
        "db-cql",
        "db-data-import",
        "db-manage-thirdpartymetrics"
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "b73e44b2-b9e9-43b8-a7c1-c6a2fe2dab50",
    "name": "R/W User",
    "policy": {
      "description": "R/W User",
      "resources": [
        "drn:astra:org:__ORG_ID__",
        "drn:astra:org:__ORG_ID__:db:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*"
      ],
      "actions": [
        "accesslist-read",
        "org-db-view",
        "org-user-read",
        "db-all-keyspace-describe",
        "db-keyspace-describe",
        "db-table-select",
        "db-table-modify",
        "db-table-describe",
        "db-graphql",
        "db-rest",
        "db-cql"
       ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "90df373f-f8e2-49ad-9db2-ddbb9b88eec8",
    "name": "DATABASE_NAME Database Administrator",
    "policy": {
      "description": "DATABASE_NAME Database Administrator",
      "resources": [
        "drn:astra:org:RESOLVED_ORG_ID",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:*:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system_schema:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system_virtual_schema:table:*"
      ],
      "actions": [
        "accesslist-read",
        "accesslist-write",
        "org-cmk-read",
        "org-cmk-write",
        "org-db-create",
        "org-db-passwordreset",
        "org-db-terminate",
        "org-db-suspend",
        "org-db-addpeering",
        "org-db-managemigratorproxy",
        "org-db-expand",
        "org-db-view",
        "org-role-read",
        "org-token-read",
        "org-token-write",
        "org-user-read",
        "db-manage-privateendpoint",
        "db-all-keyspace-create",
        "db-all-keyspace-describe",
        "db-keyspace-grant",
        "db-keyspace-modify",
        "db-keyspace-describe",
        "db-keyspace-create",
        "db-keyspace-authorize",
        "db-keyspace-alter",
        "db-keyspace-drop",
        "db-manage-region",
        "db-table-select",
        "db-table-grant",
        "db-table-modify",
        "db-table-describe",
        "db-table-create",
        "db-table-authorize",
        "db-table-alter",
        "db-table-drop",
        "db-graphql",
        "db-rest",
        "db-cql",
        "db-data-import",
        "db-manage-thirdpartymetrics"
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  }
]

If you want to inspect details for one role, use GET /v2/organizations/roles/ROLE_ID.

Create a custom role

Astra Portal
DevOps API

Create a custom organization role
Create a custom enterprise role

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 custom role.

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 Roles.
Click Add Custom Role.
Enter a name for the role.
Select permissions to grant to the role.
In the Add Databases section, define the role’s resource scope. You can select specific databases and keyspaces or enable Apply permissions to all databases in this organization to allow access to all current and future databases, as well as the keyspaces within those databases.
Click Create Role.

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 Roles.
Click Add Custom Role.
Enter a name for the role.
Assign enterprise permissions and resource scope.
Click Create Custom Role.

Next, assign the role to a user or application token.

You can use the DevOps API to create custom organization roles.

Use GET /v2/organizations/roles to get a template for the custom role configuration:

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

The response includes information about all default and custom roles in your organization. Pick any role that is similar to your new role, and then copy the role’s name and policy, including all policy subfields (description,resources, actions, and effect).

Result

[
  {
    "id": "ad0566b5-2a67-49de-89e8-92258c2f2c98",
    "name": "Organization Administrator",
    "policy": {
      "description": "Organization Administrator",
      "resources": [
        "drn:astra:org:__ORG_ID__",
        "drn:astra:org:__ORG_ID__:db:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*",
        "drn:astra:org:__ORG_ID__:stream:*",
        "drn:astra:org:__ORG_ID__:role:*"
      ],
      "actions": [
        "accesslist-read",
        "accesslist-write",
        "org-read",
        "org-write",
        "org-audits-read",
        "org-cmk-read",
        "org-cmk-write",
        "org-role-read",
        "org-role-write",
        "org-role-delete",
        "org-external-auth-read",
        "org-external-auth-write",
        "org-notification-write",
        "org-token-read",
        "org-token-write",
        "org-billing-read",
        "org-billing-write",
        "org-user-read",
        "org-user-write",
        "org-db-create",
        "org-db-passwordreset",
        "org-db-terminate",
        "org-db-suspend",
        "org-db-addpeering",
        "org-db-managemigratorproxy",
        "org-db-expand",
        "org-db-view",
        "org-integrations-read",
        "org-integrations-write",
        "org-stream-manage",
        "db-manage-privateendpoint",
        "db-all-keyspace-create",
        "db-all-keyspace-describe",
        "db-keyspace-grant",
        "db-keyspace-modify",
        "db-keyspace-describe",
        "db-keyspace-create",
        "db-keyspace-authorize",
        "db-keyspace-alter",
        "db-keyspace-drop",
        "db-manage-region",
        "db-table-select",
        "db-table-grant",
        "db-table-modify",
        "db-table-describe",
        "db-table-create",
        "db-table-authorize",
        "db-table-alter",
        "db-table-drop",
        "db-graphql",
        "db-rest",
        "db-cql",
        "db-data-import",
        "db-manage-thirdpartymetrics"
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "b73e44b2-b9e9-43b8-a7c1-c6a2fe2dab50",
    "name": "R/W User",
    "policy": {
      "description": "R/W User",
      "resources": [
        "drn:astra:org:__ORG_ID__",
        "drn:astra:org:__ORG_ID__:db:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*"
      ],
      "actions": [
        "accesslist-read",
        "org-db-view",
        "org-user-read",
        "db-all-keyspace-describe",
        "db-keyspace-describe",
        "db-table-select",
        "db-table-modify",
        "db-table-describe",
        "db-graphql",
        "db-rest",
        "db-cql"
       ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "90df373f-f8e2-49ad-9db2-ddbb9b88eec8",
    "name": "DATABASE_NAME Database Administrator",
    "policy": {
      "description": "DATABASE_NAME Database Administrator",
      "resources": [
        "drn:astra:org:RESOLVED_ORG_ID",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:*:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system_schema:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system_virtual_schema:table:*"
      ],
      "actions": [
        "accesslist-read",
        "accesslist-write",
        "org-cmk-read",
        "org-cmk-write",
        "org-db-create",
        "org-db-passwordreset",
        "org-db-terminate",
        "org-db-suspend",
        "org-db-addpeering",
        "org-db-managemigratorproxy",
        "org-db-expand",
        "org-db-view",
        "org-role-read",
        "org-token-read",
        "org-token-write",
        "org-user-read",
        "db-manage-privateendpoint",
        "db-all-keyspace-create",
        "db-all-keyspace-describe",
        "db-keyspace-grant",
        "db-keyspace-modify",
        "db-keyspace-describe",
        "db-keyspace-create",
        "db-keyspace-authorize",
        "db-keyspace-alter",
        "db-keyspace-drop",
        "db-manage-region",
        "db-table-select",
        "db-table-grant",
        "db-table-modify",
        "db-table-describe",
        "db-table-create",
        "db-table-authorize",
        "db-table-alter",
        "db-table-drop",
        "db-graphql",
        "db-rest",
        "db-cql",
        "db-data-import",
        "db-manage-thirdpartymetrics"
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  }
]

Use POST /v2/organizations/roles to create a custom role:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/organizations/roles" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "ROLE_NAME",
  "policy": {
    "description": "ROLE_NAME",
    "resources": [
      "RESOURCE_ID",
      "RESOURCE_ID",
      "RESOURCE_ID"
    ],
    "actions": [
      "PERMISSION_NAME",
      "PERMISSION_NAME"
    ],
    "effect": "allow"
  }
}'

Use the name, and policy that you copied from GET /v2/organizations/roles as the basis of the POST request body:

name and policy.description: Enter the role name in both of these parameters.
policy.resources: Provide an array of resource IDs to define the role’s access to Astra resources. For more information, see Resource scopes.
policy.actions: Provide an array of permissions to grant to the role. Use the DevOps API parameter name for each permission, not the Astra Portal display name.
policy.effect: Must be allow.

Custom API role policy examples

These examples describe custom API roles that you could assign to an application token. They are considered API roles because they don’t have the org-db-view permission that is required to access the Astra Portal.

The following role can only edit one table within a specific keyspace:

"name": "API_MODIFY_ONLY_TABLE1",
"policy": {
  "description": "API_MODIFY_ONLY_TABLE1",
  "resources": [
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:default_keyspace:table:table1"
  ],
  "actions": [
    "db-table-select",
    "db-table-describe",
    "db-table-grant",
    "db-table-alter",
    "db-table-authorize",
    "db-table-modify"
  ],
  "effect": "allow"
}

The following role can edit all tables within three specific keyspaces:

"name": "API_MODIFY_ALL_TABLES",
"policy": {
  "description": "API_MODIFY_ALL_TABLES",
  "resources": [
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:default_keyspace:table:*"
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:second_keyspace:table:*"
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:third_keyspace:table:*"
  ],
  "actions": [
    "db-table-select",
    "db-table-describe",
    "db-table-grant",
    "db-table-alter",
    "db-table-authorize",
    "db-table-modify"
  ],
  "effect": "allow"
}

The following role has read-only access to all tables in all keyspaces in one database:

"name": "API_READ_ONLY",
"policy": {
  "description": "API_READ_ONLY",
  "resources": [
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:*"
  ],
  "actions": [
    "db-table-select",
    "db-table-describe"
  ],
  "effect": "allow"
}

For additional examples of API and user roles, use GET /v2/organizations/roles.

A successful response includes the new role’s id as well as the name and policy you specified. If you try to create a role that already exists, the server returns 409 Conflict and the message unable to update custom role data.

Edit a custom role

You can edit any custom roles in your enterprise or organization, including custom DATABASE_NAME Database Administrator roles that Astra creates when you generate an application token for a database.

After you edit a custom role, it can take several minutes for the changes to propagate to all tokens and users that are assigned to that role.

When you edit a custom role, consider the effects that your changes can have on existing tokens and users assigned to that role. For example, revoking necessary permissions from a production token can cause an application to fail. 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.

Astra Portal
DevOps API

Edit a custom organization role
Edit a custom enterprise role

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 edit a custom role.

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 Roles.
Find the role you want to edit, click More, and then select Edit Role.
Modify the role’s name and permissions as necessary, and then click Edit Role.

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 Roles.
Find the role you want to edit, click More, and then select Edit Role.

You can use the DevOps API to edit custom organization roles.

A role’s policy object is a desired state list. When you use the DevOps API to edit a role, use the existing policy as a template to ensure that you don’t unintentionally remove any permissions.

Use GET /v2/organizations/roles to get the role’s current configuration:

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

The response includes information about all default and custom roles in your organization. Find the custom role you want to edit, and then copy the id, name, and the entire policy object, including all policy subfields (description,resources, actions, and effect).

Result

[
  {
    "id": "ad0566b5-2a67-49de-89e8-92258c2f2c98",
    "name": "Organization Administrator",
    "policy": {
      "description": "Organization Administrator",
      "resources": [
        "drn:astra:org:__ORG_ID__",
        "drn:astra:org:__ORG_ID__:db:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*",
        "drn:astra:org:__ORG_ID__:stream:*",
        "drn:astra:org:__ORG_ID__:role:*"
      ],
      "actions": [
        "accesslist-read",
        "accesslist-write",
        "org-read",
        "org-write",
        "org-audits-read",
        "org-cmk-read",
        "org-cmk-write",
        "org-role-read",
        "org-role-write",
        "org-role-delete",
        "org-external-auth-read",
        "org-external-auth-write",
        "org-notification-write",
        "org-token-read",
        "org-token-write",
        "org-billing-read",
        "org-billing-write",
        "org-user-read",
        "org-user-write",
        "org-db-create",
        "org-db-passwordreset",
        "org-db-terminate",
        "org-db-suspend",
        "org-db-addpeering",
        "org-db-managemigratorproxy",
        "org-db-expand",
        "org-db-view",
        "org-integrations-read",
        "org-integrations-write",
        "org-stream-manage",
        "db-manage-privateendpoint",
        "db-all-keyspace-create",
        "db-all-keyspace-describe",
        "db-keyspace-grant",
        "db-keyspace-modify",
        "db-keyspace-describe",
        "db-keyspace-create",
        "db-keyspace-authorize",
        "db-keyspace-alter",
        "db-keyspace-drop",
        "db-manage-region",
        "db-table-select",
        "db-table-grant",
        "db-table-modify",
        "db-table-describe",
        "db-table-create",
        "db-table-authorize",
        "db-table-alter",
        "db-table-drop",
        "db-graphql",
        "db-rest",
        "db-cql",
        "db-data-import",
        "db-manage-thirdpartymetrics"
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "b73e44b2-b9e9-43b8-a7c1-c6a2fe2dab50",
    "name": "R/W User",
    "policy": {
      "description": "R/W User",
      "resources": [
        "drn:astra:org:__ORG_ID__",
        "drn:astra:org:__ORG_ID__:db:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*",
        "drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*"
      ],
      "actions": [
        "accesslist-read",
        "org-db-view",
        "org-user-read",
        "db-all-keyspace-describe",
        "db-keyspace-describe",
        "db-table-select",
        "db-table-modify",
        "db-table-describe",
        "db-graphql",
        "db-rest",
        "db-cql"
       ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "90df373f-f8e2-49ad-9db2-ddbb9b88eec8",
    "name": "DATABASE_NAME Database Administrator",
    "policy": {
      "description": "DATABASE_NAME Database Administrator",
      "resources": [
        "drn:astra:org:RESOLVED_ORG_ID",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:*:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system_schema:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system:table:*",
        "drn:astra:org:RESOLVED_ORG_ID:db:DB_ID:keyspace:system_virtual_schema:table:*"
      ],
      "actions": [
        "accesslist-read",
        "accesslist-write",
        "org-cmk-read",
        "org-cmk-write",
        "org-db-create",
        "org-db-passwordreset",
        "org-db-terminate",
        "org-db-suspend",
        "org-db-addpeering",
        "org-db-managemigratorproxy",
        "org-db-expand",
        "org-db-view",
        "org-role-read",
        "org-token-read",
        "org-token-write",
        "org-user-read",
        "db-manage-privateendpoint",
        "db-all-keyspace-create",
        "db-all-keyspace-describe",
        "db-keyspace-grant",
        "db-keyspace-modify",
        "db-keyspace-describe",
        "db-keyspace-create",
        "db-keyspace-authorize",
        "db-keyspace-alter",
        "db-keyspace-drop",
        "db-manage-region",
        "db-table-select",
        "db-table-grant",
        "db-table-modify",
        "db-table-describe",
        "db-table-create",
        "db-table-authorize",
        "db-table-alter",
        "db-table-drop",
        "db-graphql",
        "db-rest",
        "db-cql",
        "db-data-import",
        "db-manage-thirdpartymetrics"
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  }
]

Use PUT /v2/organizations/roles/ROLE_ID to edit the role.

curl -sS -L -X PUT "https://api.astra.datastax.com/v2/organizations/roles/ROLE_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "ROLE_NAME",
  "policy": {
    "description": "ROLE_NAME",
    "resources": [
      "RESOURCE_ID",
      "RESOURCE_ID",
      "RESOURCE_ID"
    ],
    "actions": [
      "PERMISSION_NAME",
      "PERMISSION_NAME"
    ],
    "effect": "allow"
  }
}'

Use the name, and policy that you copied from GET /v2/organizations/roles as the basis of the PUT request body:

name and policy.description: To change the role’s display name, change both of these values.
policy.resources: Provide an array of resource IDs to define the role’s access to Astra resources. For more information, see Resource scopes.
policy.actions: Provide an array of permissions to grant to the role. Use the DevOps API parameter name for each permission, not the Astra Portal display name.
policy.effect: Must be allow.

Custom role policy example

The following example defines a narrowly-scoped role that can only edit one table within a specific keyspace:

"name": "API_MODIFY_ONLY_TABLE1",
"policy": {
  "description": "API_MODIFY_ONLY_TABLE1",
  "resources": [
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:default_keyspace:table:table1"
  ],
  "actions": [
    "db-table-select",
    "db-table-describe"
    "db-table-grant",
    "db-table-alter",
    "db-table-authorize",
    "db-table-modify",
  ],
  "effect": "allow"
}

For additional examples, see Create a custom role.

Optional: To review the applied policy, use GET /v2/organizations/roles/ROLE_ID.

Delete a custom role

Deleting a custom role removes it from all users and application tokens it is assigned to. Before deleting a custom role, reassign any users with the role to other roles and generate new application tokens with different roles, as needed to ensure continuity of access.

Astra Portal
DevOps API

Delete a custom organization role
Delete a custom enterprise role

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 custom role.

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 Roles.
Find the role you want to delete, click More, and then select Delete Role.
In the confirmation dialog, click Delete Role.

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 Roles.
Find the role you want to delete, click More, and then select Delete Role.

Use GET /v2/organizations/roles to get the IDs of the roles that you want to delete:

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

The response includes information about all default and custom roles in your organization. Copy the id for each custom role that you want to delete. You can’t delete default roles.

Result

The following example is truncated for clarity.

[
  {
    "id": "b4ed0e9e-67e8-47b6-8b58-c6629be961a9",
    "name": "R/W Svc Acct",
    "policy": {
      "description": "R/W Svc Acct",
      "resources": [
        ...
      ],
      "actions": [
        ...
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
  {
    "id": "43745b73-ad46-46e4-b826-c15d06d2cea0",
    "name": "Admin User",
    "policy": {
      "description": "Admin User",
      "resources": [
        ...
      ],
      "actions": [
        ...
      ],
      "effect": "allow"
    },
    "last_update_date_time": "0001-01-01T00:00:00Z",
    "last_update_user_id": ""
  },
]

Use DELETE /v2/organizations/roles/ROLE_ID to delete the role:

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

A successful request returns 204 No Content.

Optional: To verify that the role was deleted, use GET /v2/organizations/roles/ROLE_ID.

Assign roles

Roles contain permissions and resource scopes that define the access and actions available to that role. You assign roles to users and application tokens. Then, users and apps can interact with your enterprise, organization, and databases according to the permissions granted by the assigned roles.

For information about assigning roles to users and editing role assignments, see Manage users.

For information about role assignment for application tokens, see Use application tokens.

Permissions

Permissions define the actions that an entity can take on a resource, such as a database, keyspace, or an entire organization. Possible actions range from limited read-only operations to expansive create, edit, and delete operations.

The following tables describe permissions available in Astra DB Classic.

Each permission has a Permission name that is visible in the Astra Portal as well as a DevOps API parameter value for role management with the DevOps API.

Unless otherwise specified, permissions grant the ability to perform a function both in the Astra Portal and programmatically, such as through an API or the Astra CLI.

Enterprise permissions

Enterprise permissions define the operations a role can perform at the enterprise level, such as adding enterprise users, adding organizations to the enterprise, and creating enterprise application tokens.

Enterprise roles are separate from organization roles, which means that enterprise permissions don’t inherently grant the equivalent organization permissions.

For example, the ent-role-read permission doesn’t include org-role-read. With ent-role-read, you can view default and custom enterprise roles only. If you want to view both enterprise and organization roles, you must have an enterprise role with the ent-role-read permission and an organization role with the org-role-read permission. If your enterprise has multiple organizations, you need an organization role in each organization that you want to view.

For more information about the relationship between enterprise and organization roles, see Enterprise users and roles.

Permission name DevOps API parameter Description

Permission name	DevOps API parameter	Description
Read Enterprise Billing	`ent-billing-read`	Retrieve billing details for organizations in an enterprise.
Write Enterprise Billing	`ent-billing-write`	This permission is inactive. To manage billing for an organization, use Write Billing.
Read Enterprise User	`ent-user-read`	View users in an enterprise. To view users in an organization, use Read User.
Write Enterprise User	`ent-user-write`	Modify users at the enterprise level: Invite users to the enterprise Revoke enterprise-level user invitations Change enterprise role assignments Remove enterprise-level users To manage users within an organization, use Write User.
Read Enterprise Token	`ent-token-read`	View enterprise application tokens.
Write Enterprise Token	`ent-token-write`	Create and revoke enterprise application tokens.
Manage Enterprise Organization	`ent-org-manage`	Create an organization under an enterprise.
Read Enterprise Role	`ent-role-read`	View custom enterprise roles and their associated permissions.
Write Enterprise Role	`ent-role-write`	Create, edit, and delete custom enterprise roles.

Read Enterprise Billing

ent-billing-read

Retrieve billing details for organizations in an enterprise.

Write Enterprise Billing

ent-billing-write

This permission is inactive. To manage billing for an organization, use Write Billing.

Read Enterprise User

ent-user-read

View users in an enterprise.

To view users in an organization, use Read User.

Write Enterprise User

ent-user-write

Modify users at the enterprise level:

Invite users to the enterprise
Revoke enterprise-level user invitations
Change enterprise role assignments
Remove enterprise-level users

To manage users within an organization, use Write User.

Read Enterprise Token

ent-token-read

View enterprise application tokens.

Write Enterprise Token

ent-token-write

Create and revoke enterprise application tokens.

Manage Enterprise Organization

ent-org-manage

Create an organization under an enterprise.

Read Enterprise Role

ent-role-read

View custom enterprise roles and their associated permissions.

Write Enterprise Role

ent-role-write

Create, edit, and delete custom enterprise roles.

Organization permissions

Organization permissions define the operations a role can perform at the organization level, such as billing administration, user administration, and the ability to create databases.

Organization permissions related to database management, such as Manage Region and View DB, can be further limited to specific databases.

To view the Astra Portal, a role must have the View DB permission.

Permission name DevOps API parameter Description

Permission name	DevOps API parameter	Description
Add Peering	`org-db-addpeering`	Create a VPC peering connection for an Astra DB Classic database.
Create DB	`org-db-create`	Create a database.
Delete Custom Role	`org-role-delete`	Delete a custom role.
Expand DB	`org-db-expand`	Resize an Astra DB Classic database.
Manage Metrics	`db-manage-thirdpartymetrics`	Manage health metrics export destinations.
Manage Migrator Proxy	`org-db-managemigratorproxy`	(Inactive) Manage the ZDM proxy tool for Astra DB Classic databases. This permission is inactive because the ZDM proxy is no longer bundled with Astra DB Classic databases. However, you can still use ZDM proxy to migrate data to Astra DB databases.
Manage Private Endpoint	`db-manage-privateendpoint`	Configure private endpoints.
Manage Region	`db-manage-region`	Add or remove regions from multi-region databases.
Manage Streaming	`org-stream-manage`	View, add, edit, or remove Astra Streaming configurations. a[#password-reset-permission] Password Reset
`org-db-passwordreset`	(Inactive) Use the DevOps API to reset the password associated with an Astra DB Classic database. This permission is inactive because this functionality is deprecated. For database access, use an application token or Secure Connect Bundle (SCB).	Read Audits
`org-audits-read`	Download organization audit logs in the Astra Portal.	Read Billing
`org-billing-read`	Access the Billing page and download invoices in the Astra Portal.	Read CMK Key
`org-cmk-read`	View customer keys in an organization.	Read Custom Role
`org-role-read`	View custom roles and their associated permissions.	Read External Auth
`org-external-auth-read`	View an organization’s SSO configuration in the Astra Portal.	Read Integrations
`org-integrations-read`	View an organization’s enabled integrations on the Integrations page in the Astra Portal.	Read IP Access List
`accesslist-read`	View database and DevOps API IP access lists. Visibility of database access lists depends on the role’s resource scopes.	Read Organization
`org-read`	View an organization.	Read Token
`org-token-read`	View application tokens in an organization.	Read User
`org-user-read`	View users in an organization.	Suspend DB
`org-db-suspend`	(Inactive) Suspend/unsuspend an Astra DB Classic database. This permission is inactive because this functionality is deprecated.	Terminate DB
`org-db-terminate`	Permanently delete a database and all of of its data.	View DB
`org-db-view`	View the Astra Portal generally. View databases in the Astra Portal. View database information returned by an API request.	Write Billing
`org-billing-write`	Modify the organization’s payment method and PCU groups.	Write CMK Key
`org-cmk-write`	Create and manage customer keys.	Write Custom Role
`org-role-write`	Create and manage custom roles.	Write External Auth
`org-external-auth-write`	Manage an organization’s SSO configuration in the Astra Portal.	Write Integrations
`org-integrations-write`	Add, edit, and remove an organization’s integrations on the Integrations page in the Astra Portal.	Write IP Access List
`accesslist-write`	Create and modify database and DevOps API IP access lists. Access to database access lists depends on the role’s resource scopes.	Write Organization
`org-write`	Grants the following: Delete an organization Edit organization settings not controlled by another permission, such as the organization’s name or description	Write Token
`org-token-write`	Create application tokens.	Write User

Add Peering

org-db-addpeering

Create a VPC peering connection for an Astra DB Classic database.

Create DB

org-db-create

Create a database.

Delete Custom Role

org-role-delete

Delete a custom role.

Expand DB

org-db-expand

Resize an Astra DB Classic database.

Manage Metrics

db-manage-thirdpartymetrics

Manage health metrics export destinations.

Manage Migrator Proxy

org-db-managemigratorproxy

(Inactive) Manage the ZDM proxy tool for Astra DB Classic databases. This permission is inactive because the ZDM proxy is no longer bundled with Astra DB Classic databases. However, you can still use ZDM proxy to migrate data to Astra DB databases.

Manage Private Endpoint

db-manage-privateendpoint

Configure private endpoints.

Manage Region

db-manage-region

Add or remove regions from multi-region databases.

Manage Streaming

org-stream-manage

View, add, edit, or remove Astra Streaming configurations.

a[#password-reset-permission] Password Reset

org-db-passwordreset

(Inactive) Use the DevOps API to reset the password associated with an Astra DB Classic database. This permission is inactive because this functionality is deprecated. For database access, use an application token or Secure Connect Bundle (SCB).

Read Audits

org-audits-read

Download organization audit logs in the Astra Portal.

Read Billing

org-billing-read

Access the Billing page and download invoices in the Astra Portal.

Read CMK Key

org-cmk-read

View customer keys in an organization.

Read Custom Role

org-role-read

View custom roles and their associated permissions.

Read External Auth

org-external-auth-read

View an organization’s SSO configuration in the Astra Portal.

Read Integrations

org-integrations-read

View an organization’s enabled integrations on the Integrations page in the Astra Portal.

Read IP Access List

accesslist-read

View database and DevOps API IP access lists. Visibility of database access lists depends on the role’s resource scopes.

Read Organization

org-read

View an organization.

Read Token

org-token-read

View application tokens in an organization.

Read User

org-user-read

View users in an organization.

Suspend DB

org-db-suspend

(Inactive) Suspend/unsuspend an Astra DB Classic database. This permission is inactive because this functionality is deprecated.

Terminate DB

org-db-terminate

Permanently delete a database and all of of its data.

View DB

org-db-view

View the Astra Portal generally. View databases in the Astra Portal. View database information returned by an API request.

Write Billing

org-billing-write

Modify the organization’s payment method and PCU groups.

Write CMK Key

org-cmk-write

Create and manage customer keys.

Write Custom Role

org-role-write

Create and manage custom roles.

Write External Auth

org-external-auth-write

Manage an organization’s SSO configuration in the Astra Portal.

Write Integrations

org-integrations-write

Add, edit, and remove an organization’s integrations on the Integrations page in the Astra Portal.

Write IP Access List

accesslist-write

Create and modify database and DevOps API IP access lists. Access to database access lists depends on the role’s resource scopes.

Write Organization

org-write

Grants the following:

Delete an organization
Edit organization settings not controlled by another permission, such as the organization’s name or description

Write Token

org-token-write

Create application tokens.

Write User

Keyspace permissions

Keyspace permissions apply to keyspaces within your Astra DB Classic databases. You can use resource scopes to further restrict a role’s access to individual keyspaces and resources within keyspaces.

Permission name DevOps API parameter Description

Permission name	DevOps API parameter	Description
Alter Keyspace	`db-keyspace-alter`	Add, edit, or remove a keyspace’s configuration or tables, such as with CQL `ALTER`.
Authorize Keyspace	`db-keyspace-authorize`	Grant admin permissions on a keyspace, such as with CQL `AUTHORIZE`.
Create All Keyspaces	`db-all-keyspace-create`	Create keyspaces programmatically.
Create Keyspace	`db-keyspace-create`	Create a keyspace in the Astra Portal.
Describe All Keyspaces	`db-all-keyspace-describe`	Get a list of tables in multiple keyspaces, such as with CQL `DESCRIBE`.
Describe Keyspace	`db-keyspace-describe`	Get a list of tables within a single keyspace.
Drop Keyspace	`db-keyspace-drop`	Remove a keyspace.
Grant Keyspace	`db-keyspace-grant`	Grant specific permissions on a keyspace, such as with CQL `GRANT`.
Modify Keyspace	`db-keyspace-modify`	Edit a keyspace (a limited version of Alter Keyspace).

Alter Keyspace

db-keyspace-alter

Add, edit, or remove a keyspace’s configuration or tables, such as with CQL ALTER.

Authorize Keyspace

db-keyspace-authorize

Grant admin permissions on a keyspace, such as with CQL AUTHORIZE.

Create All Keyspaces

db-all-keyspace-create

Create keyspaces programmatically.

Create Keyspace

db-keyspace-create

Create a keyspace in the Astra Portal.

Describe All Keyspaces

db-all-keyspace-describe

Get a list of tables in multiple keyspaces, such as with CQL DESCRIBE.

Describe Keyspace

db-keyspace-describe

Get a list of tables within a single keyspace.

Drop Keyspace

db-keyspace-drop

Remove a keyspace.

Grant Keyspace

db-keyspace-grant

Grant specific permissions on a keyspace, such as with CQL GRANT.

Modify Keyspace

db-keyspace-modify

Edit a keyspace (a limited version of Alter Keyspace).

Table permissions

These permissions apply to tables within your Astra DB Classic databases. You can use database, keyspace, and table scopes to further restrict table permissions.

Permission name DevOps API parameter Description

Permission name	DevOps API parameter	Description
Alter Table	`db-table-alter`	Add, edit, or remove a table’s columns, such as with CQL `ALTER`.
Authorize Table	`db-table-authorize`	Grant admin permissions on a table, such as with CQL `AUTHORIZE`.
Create Table	`db-table-create`	Create a table.
Describe Table	`db-table-describe`	Get table information, such as with CQL `DESCRIBE`.
Drop Table	`db-table-drop`	Delete a table.
Grant Table	`db-table-grant`	Grant specific permissions on a table, such as with CQL `GRANT`.
Modify Table	`db-table-modify`	Edit a table (a limited version of Alter Table).
Select Table	`db-table-select`	Use CQL `SELECT` on a table.

Alter Table

db-table-alter

Add, edit, or remove a table’s columns, such as with CQL ALTER.

Authorize Table

db-table-authorize

Grant admin permissions on a table, such as with CQL AUTHORIZE.

Create Table

db-table-create

Create a table.

Describe Table

db-table-describe

Get table information, such as with CQL DESCRIBE.

Drop Table

db-table-drop

Delete a table.

Grant Table

db-table-grant

Grant specific permissions on a table, such as with CQL GRANT.

Modify Table

db-table-modify

Edit a table (a limited version of Alter Table).

Select Table

db-table-select

Use CQL SELECT on a table.

API access permissions

API access permissions grant a role access to databases through the CQL Console and some legacy APIs.

You can’t control access to the DevOps API on a role level. Instead, you authenticate to this API with an application token that determines the operations you can perform through that API.

Permission name DevOps API parameter Description

Permission name	DevOps API parameter	Description
Access CQL	`db-cql`	Connect to database through the CQL.
Access GraphQL	`db-graphql`	Connect to database through the GraphQL API (deprecated).
Access REST	`db-rest`	Connect to database through the REST API (deprecated).

Access CQL

db-cql

Connect to database through the CQL.

Access GraphQL

db-graphql

Connect to database through the GraphQL API (deprecated).

Access REST

db-rest

Connect to database through the REST API (deprecated).

Resource scopes

Default roles can access all databases, keyspaces, and tables in an Astra organization. This includes existing instances of these resources as well as any instances you create in the future.

For custom roles, you can define resource scopes that limit access to resources like databases, keyspaces, and tables. Resource scopes apply an additional layer of restriction on top of the permissions granted to the role. For example, if you have a role with the Create Keyspace permission, and you limit that role to a specific database, then that role can only create keyspaces within that specific database.

Scopes restrict all permissions for the role, wherever applicable. For example, if you limit the scope for a role with the View DB and Create Keyspace permissions, the scope applies to both of those permissions.

If you need to mix scopes and permissions, you must create multiple custom roles with the required scopes. For example, you could create a View Production DBs role that has View DB permission scope to only your production databases, and a Manage Dev DBs role that has permission to view and edit development databases.

Define resource scopes

Astra Portal
DevOps API

The Astra Portal provides limited control over resource scopes when you create or edit custom roles:

All databases: Grant access to all databases in the organization, including those currently existing and future databases. This includes all existing and future keyspaces and tables in all databases.
Specific databases and keyspaces: Grant access to specific existing databases and existing keyspaces in those databases. You can choose either all existing keyspaces or specific existing keyspaces. Future keyspaces are not included, but all existing and future tables in the selected keyspaces are included.

If you limit a role’s scope to specific databases and keyspaces, you must manually update the role to include new databases and keyspaces that you create in the future.

If you need more control over resource scopes, use the DevOps API.

With the DevOps API, you can define highly granular and variable resource scopes when you create or edit custom roles.

A role’s resource scope is an array of resource IDs. For example:

"resources":[
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:system_schema:table:*",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:system:table:*",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:system_virtual_schema:table:*",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:default_keyspace",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:default_keyspace:table:*",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:other_keyspace",
    "drn:astra:org:b6bbc50b-8164-5f59-a3b1-55a8196b352e:db:b7aafc99-b1fe-492c-b130-73cad3c008cc:keyspace:other_keyspace:table:*"
  ],

Get examples of resource scopes

To get examples of resource scopes, use GET /v2/organizations/roles:

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

For each role, the response includes the id, name, policy, and last_update metadata. The policy object contains the resources array.

For default roles, resource IDs include literally ORG_ID instead of a resolved organization ID. Custom roles include the fully resolved organization ID in each resource ID.

The broadest resource ID is drn:astra:org:ORG_ID, which grants access to your Astra organization within the bounds of the role’s permissions.

Narrower resource IDs append multiple suffixes to reduce the scope to resources within the organization. For example, the following resource IDs grant access to specific resources, identified by name or ID:

# Access to the organization
"drn:astra:org:ORG_ID"

# Access to a specific database
"drn:astra:org:ORG_ID:db:DB_ID"

# Access to a specific keyspace in a database
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:KEYSPACE_NAME"

# Access to a specific table in a keyspace
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:KEYSPACE_NAME:table:TABLE_NAME"

You can use an asterisk (*) as a wildcard to grant access to all instances of a resource type, including existing and future instances of that type:

# Access to all databases in an organization
"drn:astra:org:ORG_ID:db:*"

# Access to all keyspaces in a specific database
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:*"

# Access to all tables in a specific keyspace
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:KEYSPACE_NAME:table:*"

# Access to all streaming tenants in an organization
"drn:astra:org:ORG_ID:stream:*"

Access to a higher-level resource inherently grants access to associated lower-level resources, unless you explicitly define a narrower resource ID.

For example, the resource ID drn:astra:org:ORG_ID:db:DB_ID grants access to all keyspaces and tables within the specified database. If the policy also includes drn:astra:org:ORG_ID:db:DB_ID:keyspace:KEYSPACE_NAME, then the role is limited to the specified keyspace and its tables, rather than the entire database.

If you use a wildcard, place it at the lowest possible level to avoid granting excessive access. For example, the resource ID drn:astra:org:ORG_ID:db:* grants access to all current and future databases, keyspaces, and tables in the organization. In contrast, drn:astra:org:ORG_ID:db:DB_ID:keyspace:* grants access to all current and future keyspaces and tables within a single database.
Custom role scopes are limited to the resources named in the policy, unless you use a wildcard. When you create new databases, keyspaces, or tables, you might need to edit narrowly-scoped custom roles to include the new resources, if necessary.

Troubleshoot custom roles

If you encounter issues with a custom role, try the following:

Use GET /v2/organizations/roles to retrieve role policies for other roles in your organization.
Compare your role’s policy with other polices to ensure the role has the necessary permissions and resource scopes.

If the role requires access to the Astra Portal, the policy must include the org-db-view permission and access to the drn:astra:org:ORG_ID resource.
Make sure resources contains the correct IDs and names for each resource.
If you encounter issues with a custom role that aren’t resolved by other policy modifications, the policy might require certain resource IDs for minimal functionality. In addition to drn:astra:org:ORG_ID, which grants access to the organization itself, policies that reach the keyspace level might require access to the following system keyspaces and tables. These resources aren’t directly manipulated by the user.
```
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:system_schema:table:*"
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:system:table:*"
"drn:astra:org:ORG_ID:db:DB_ID:keyspace:system_virtual_schema:table:*"
```

Manage roles and permissions

Default roles

Custom roles

View roles

Create a custom role

Edit a custom role

Delete a custom role

Assign roles

Permissions

Enterprise permissions

Organization permissions

Keyspace permissions

Table permissions

API access permissions

Resource scopes

Define resource scopes

See also

Was this helpful?

Give Feedback