Managing roles

Use the DevOps API to create, modify, and delete roles for your organization.

You can use the DevOps API to perform the actions your role permissions allow.

Use a token with the Organization Administrator role, which by default has the correct set of permissions to manage your organization. Or create a custom role that includes Organization Administrator. Do not use the Database Adminstrator role; it lacks the permissions needed to manage your organization.

Prerequisites

Create an application token to authenticate your service account in the DevOps API.
Once you have authenticated your service account, you can create, update, and delete roles in the DevOps API.

Creating a new role

Submit a GET query to check existing roles within the organization to ensure you don’t duplicate roles:

cURL command (/v2)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/organizations/roles' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

[
	{"ID":"3fb93abd-7abe-4a3d-9f71-9ded80070a4a”,
	"Name":"API Admin Svc Acct”,
	"Type":"default","policy”:”
		{\"description\":\"API Admin Svc Acct\”,
		\"actions\”:[
			\"accesslist-read\”,
			\"org-billing-read\”,
			\"org-billing-write\”,
			\"org-user-read\”,
			\"org-user-write\”,
			\"org-db-create\”,
			\"org-db-passwordreset\”,
			\"org-db-view\”,
			\"org-db-terminate\”,
			\"org-db-suspend\”,
			\"org-db-addpeering\”,
			\"org-db-managemigratorproxy\”,
			\"org-db-expand\”,
			\"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-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\”],
		\"effect\":\"allow\”,
		\"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:*\"]}”}
	}
]

Create a new role for your organization:

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/roles' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
    	"name":"<roleName>",
    	"policy": {
    	  "description": "Create and describe keyspaces",
    	  "resources": ["drn:astra:org:<organizationId>"],
    	  "actions": ["db-all-keyspace-create", "db-all-keyspace-describe"],
    	  "effect": "allow"}
    }'

{
	"OrgID":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
	"Name":"keyspaceRole",
	"Policy":"{
		\"description\":\"keyspaces\",
		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
		\"effect\":\"allow\"
		}",
	"LastUpdateDateTime":"",
	"LastUpdateUserID":"wsbCtHyXCfuSHkiKbYWHsYZa"
}

If a role with the same name already exists, you’ll get an error when trying to create the new role: "unable to create role".

You can assign actions to the following resources to determine the available permissions for the custom role you create:

Group of permissions Resource assignment options Applicable actions

Group of permissions	Resource assignment options	Applicable actions
For organization permissions (`org-`)	`drn:astra:org:<organizationId>`	`org-audits-read` `org-billing-read` `org-billing-write` `org-external-auth-read` `org-external-auth-write` `org-notification-write` `org-read` `org-role-delete` `org-role-read` `org-role-write` `org-token-read` `org-token-write` `org-user-read` `org-user-write` `org-write` `accesslist-read` `accesslist-write`
For database permissions (`org-db`)	`drn:astra:org:<organizationId>:db:*` `drn:astra:org:<organizationId>:db:<databaseId>`	`db-cql` `db-graphql` `db-rest` `org-db-addpeering` `org-db-create` `org-db-expand` `org-db-managemigratorproxy` `org-db-passwordreset` `org-db-suspend` `org-db-terminate` `org-db-view`
For keyspace permissions (`db-keyspace`)	`drn:astra:org:<organizationId>:db::keyspace:` `drn:astra:org:<organizationId>:db:<databaseId>:keyspace:*` `drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>`	`db-all-keyspace-create` `db-all-keyspace-describe` `db-keyspace-alter` `db-keyspace-authorize` `db-keyspace-create` `db-keyspace-describe` `db-keyspace-drop` `db-keyspace-grant` `db-keyspace-modify`
For table permissions (`db-table`)	`drn:astra:org:<organizationId>:db::keyspace::table:` `drn:astra:org:<organizationId>:db:<databaseId>:keyspace::table:` `drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>:table:`	`db-table-alter` `db-table-authorize` `db-table-create` `db-table-describe` `db-table-drop` `db-table-grant` `db-table-modify` `db-table-select`

For organization permissions (org-)

drn:astra:org:<organizationId>

org-audits-read
org-billing-read
org-billing-write
org-external-auth-read
org-external-auth-write
org-notification-write
org-read
org-role-delete
org-role-read
org-role-write
org-token-read
org-token-write
org-user-read
org-user-write
org-write
accesslist-read
accesslist-write

For database permissions (org-db)

drn:astra:org:<organizationId>:db:*
drn:astra:org:<organizationId>:db:<databaseId>

db-cql
db-graphql
db-rest
org-db-addpeering
org-db-create
org-db-expand
org-db-managemigratorproxy
org-db-passwordreset
org-db-suspend
org-db-terminate
org-db-view

For keyspace permissions (db-keyspace)

drn:astra:org:<organizationId>:db:*:keyspace:*
drn:astra:org:<organizationId>:db:<databaseId>:keyspace:*
drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>

db-all-keyspace-create
db-all-keyspace-describe
db-keyspace-alter
db-keyspace-authorize
db-keyspace-create
db-keyspace-describe
db-keyspace-drop
db-keyspace-grant
db-keyspace-modify

For table permissions (db-table)

drn:astra:org:<organizationId>:db:*:keyspace:*:table:*
drn:astra:org:<organizationId>:db:<databaseId>:keyspace:*:table:*
drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>:table:*

db-table-alter
db-table-authorize
db-table-create
db-table-describe
db-table-drop
db-table-grant
db-table-modify
db-table-select

If you grant access to a specified keyspace, the following permissions are allowed:

All actions for database access (org-db or db actions) are granted for the entire database, even if access is granted to only a single keyspace in the database.
Keyspace-specific access is granted for all db-keyspace actions.
Table-specific access is granted for all tables belonging to the specified keyspace.

For example, if you wanted to create a custom role that allows the users to use the REST and GraphQL APIs and also allow the role to modify tables, use the following call:

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/roles' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
  	"name":"apiRole",
  	"policy": {
  	  "description": "Access to REST and GraphQL APIs, modify tables",
  	  "resources": ["drn:astra:org:<organizationId>", "drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>:table:*"],
  	  "actions": ["db-graphql", "db-rest", "db-table-modify"],
  	  "effect": "allow"}
    }'

By using the *, the role will be able to modify all tables within the specified keyspace. If you want to grant the modify permission to a specified table, include the <tableName> in the resource.

Confirm role was created with the necessary permissions:

cURL command (/v2)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

{
	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
	"Name":"keyspaceRole",
	"policy":"{
		\"description\":\"keyspaces\",
		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
		\"effect\":\"allow\"
	}"
}

For more, see Create a role in an organization in the DevOps API.

Updating a role

If you need to make changes to the permissions for an existing role, you can change the policy:

curl --request PUT \
  --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
  	"name":"<roleName>",
  	"policy": {
  	  "description": "Create and describe keyspaces",
  	  "resources": ["drn:astra:org:<organizationId>"],
  	  "actions": ["db-all-keyspace-create", "db-all-keyspace-describe"],
  	  "effect": "allow"}
    }'

Confirm role was created with the necessary permissions:

cURL command (/v2)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

{
	"OrgID":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
	"Name":"newRoleName",
	"Policy":"{
		\"description\":\"keyspaces\",
		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
		\"effect\":\"allow\"
		}",
	"LastUpdateDateTime":"",
	"LastUpdateUserID":"wsbCtHyXCfuSHkiKbYWHsYZa"
}

For more, see Update a role within an organization in the DevOps API.

Deleting a custom role

When you delete a custom role, all users and tokens assigned to that role will no longer have access.

Delete a custom role to revoke access based on that role:

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

Confirm role no longer exists:

cURL command (/v2)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

"unable to get role for organization"

For more, see Delete a role by ID in the DevOps API.

What’s next?

Learn how to manage tokens using the DevOps API.