Manage roles and permissions

Astra DB 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 DB 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 DB 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 DB 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 DB roles
Role name	Role permissions
Organization Administrator	Grants all permissions.
Administrator Service Account	Expand to see role permissions Organization permissions Add Peering Create DB Delete Custom Role Expand DB Manage Metrics Manage Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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 Private Endpoint Manage Region Manage Streaming Read Audits Read Billing Read CMK Key Read Custom Role Read External Auth Read Integrations 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 Integrations Write IP Access List Write Organization Write Token Write User 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, you must have a role with the Read Custom Role, Write Custom Role, and Delete Custom Role permissions, such as the Organization Administrator role.

View roles

Before creating custom roles, inspect your organization’s existing custom roles to avoid duplicating roles.

When you create an application token from a database’s Overview tab, Astra DB automatically creates a custom role based on the Database Administrator default role that is scoped to that database. These roles are named DATABASE_NAME Database Administrator, and you can edit them like any other custom role.

Astra Portal
DevOps API

In the Astra Portal navigation menu, click Settings, and then click Roles. The Roles management page includes all custom roles in your organization.

If you want to inspect default roles in the Astra Portal, click Tokens. In the Select a Token Role menu, select one of the default roles to view its permissions.

Use GET /v2/organizations/roles to get information about all default and custom roles in your 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 DB 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.

Response

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

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

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

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

Response

[
  {
    "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 DB 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 organization, including custom DATABASE_NAME Database Administrator roles that Astra DB 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

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

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. Locate 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).

Response

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

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

Response

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 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 Manage 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 Serverless.

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.

Organization permissions

Organization permissions define the operations that 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 (Astra DB Classic databases only).
Create DB	`org-db-create`	Create a database.
Delete Custom Role	`org-role-delete`	Delete a custom role.
Expand DB	`org-db-expand`	Resize a database (Astra DB Classic databases only).
Manage Metrics	`db-manage-thirdpartymetrics`	Manage health metrics export destinations.
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.
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. Namely, vectorize embedding provider integrations.
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`	Suspend/unsuspend Astra DB Serverless databases (Astra DB Classic databases only).
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`	Add, edit, or remove a payment method.
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. Namely, vectorize embedding provider integrations.
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`	In the Astra Portal, create new organizations or delete an existing organization. Users can always create organizations from their default organization because they are the Organization Administrator of their default organization. Users can delete organizations only where they have the Write Organization permission, except for the default organization. For more information, see Delete an organization.
Write Token	`org-token-write`	Create application tokens.
Write User	`org-user-write`	Invite (add) users, edit users' assigned roles, and remove users from an organization.

Add Peering

org-db-addpeering

Create a VPC peering connection (Astra DB Classic databases only).

Create DB

org-db-create

Create a database.

Delete Custom Role

org-role-delete

Delete a custom role.

Expand DB

org-db-expand

Resize a database (Astra DB Classic databases only).

Manage Metrics

db-manage-thirdpartymetrics

Manage health metrics export destinations.

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.

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. Namely, vectorize embedding provider integrations.

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

Suspend/unsuspend Astra DB Serverless databases (Astra DB Classic databases only).

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

Add, edit, or remove a payment method.

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. Namely, vectorize embedding provider integrations.

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

In the Astra Portal, create new organizations or delete an existing organization.

Users can always create organizations from their default organization because they are the Organization Administrator of their default organization.

Users can delete organizations only where they have the Write Organization permission, except for the default organization. For more information, see Delete an organization.

Write Token

org-token-write

Create application tokens.

Write User

org-user-write

Invite (add) users, edit users' assigned roles, and remove users from an organization.

Keyspace permissions

Keyspace permissions apply to keyspaces within your Astra DB Serverless 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 collections and tables within your Astra DB Serverless 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 shell and some legacy APIs.

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

Permission name DevOps API parameter Description

Permission name	DevOps API parameter	Description
Access CQL	`db-cql`	Connect to database through 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 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, tables, and collections in an Astra DB 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.

In resource scopes, tables refers to both collections and tables.

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 DB 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

Organization permissions

Keyspace permissions

Table permissions

API access permissions

Resource scopes

Define resource scopes

See also

Was this helpful?

Give Feedback