Managing with DevOps API

The DevOps API allows you to manage your databases, users, and tokens.

Managing your database lifecycle

Manage your databases with the DevOps API, which can be used to create, terminate, resize, park, and unpark your database.

You can use the DevOps API to perform the actions which are available to you through your role permissions.

The following roles can use the application token to use the DevOps API:

Organization Administrator
Database Administrator
Custom roles with create, terminate, and expand database permissions

If you were on a Free or serverless (Beta) tier before 4 March 2021, you were migrated to the pay as you go plan. You will need to reconnect to your database using your application token.

Use the DevOps API to perform lifecycle actions for DataStax Astra DB databases.

To use the DevOps API, create an application token to authenticate your service account in the DevOps API.
Once you have authenticated your service account, you can create, terminate, resize, park, and unpark databases using the DevOps API.

Example

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

You cannot resize, park, or unpark serverless databases. The commands will work with only classic databases.

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.

Managing users

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

The following roles use the application token to execute DevOps API queries:

Organization Administrator
Database Administrator

Prerequisites

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

Inviting a user

Check existing users within the organization:

cURL command (/v2)
Result

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

{
"OrgID":"dacb3c32-cc2a-4bea-bd95-47ab8eb20410”,
"OrgName":"DataStax”,
"Users”:[
	{"UserID":"388def78-0040-4dge-b235-d67806929c8f”,
	"Email":"john.smith@datastax.com”,
	"Status":"active”,
	"Roles”:[{"ID":"704fc2af-9c11-4c57-b9e5-5667b8889b3e”, "Name":"Admin User”}]
	},
	{"UserID":"d8bb706b-95a0-499b-aadc-5a43b4f9042d”,
	"Email":"jane.doe@datastax.com”,
	"Status":"active”,
	"Roles”:[{"ID":"21ef3576-0197-415a-b167-d510af12ecf0”,"Name":"Organization Administrator”}]
	}]
}

Inviting a new user to your organization:

curl --request PUT \
 --url 'https://api.astra.datastax.com/v2/organizations/users' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>' \
 --data '{
     "email":"<userEmail>",
     "orgID":"<organizationId>",
     "roles": ["<roleId1>", "<roleId2>", "<roleId3>"]
   }'

For roles, use the id UUID value by Getting existing roles in your organization. The API results will show the UUID for each role id.

Your invited user must validate their email address in their invitation before they can log in to Astra.

For more, see Invite a user to an organization in the DevOps API.

Getting user information

Check for a specified user’s information within the organization:

cURL command (/v2)
Result

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

{
	"UserID":"388def78-0040-4dfe-b235-d67806939c8f",
	"Email":"sebastian.estevez@datastax.com",
	"Status":"active",
	"Roles":[{"ID":"704fc2af-9c11-4c57-b9e5-5667b8889b3e","Name":"Admin User"}]
}

For more, see Get an organization’s user in the DevOps API.

Removing a user

Delete a user by their ID:

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

Confirm user no longer exists:

cURL command (/v2)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/organizations/users/<userId>' \
 --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 Remove or uninvite a user from an organization in the DevOps API.

What’s next?

Learn how to manage tokens using the DevOps API.

Managing tokens

Use the DevOps API to generate or revoke an application token for specific roles.

You can use the DevOps API to perform the actions which are available to you through your role permissions.

The following roles can use the application token to use the DevOps API:

Organization Administrator
Database Administrator

Prerequisites

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

Alternative token management option

As an alternative to the DevOps API, consider using the Astra DB Plugin for HashiCorp Vault, for dynamic token management via vault commands. See the plugin’s documentation on our GitHub site.

Specifically, you can:

Define a default lease time
Create new tokens with lease settings
List tokens by each one’s Client ID
View lease details
List all leases
Renew a lease
Revoke a token/lease before the lease expires
Delete a token

Generating a token for client

Get all clients within the organization:

cURL command (/v2)
Result

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

{"clients":[
	{"clientId":"DkFtHKMhDQDuQtlExkSzwbya",
		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
		"generatedOn":"2021-02-22T17:09:58.668Z"},
	{"clientId":"eYSboCJaESiblJZnKZWMxROv",
		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
		"generatedOn":"2021-04-28T18:49:11.323Z"}
]}

Create an application token for a specific client:

cURL command (/v2)
Result

curl --request POST \
 --url 'https://api.astra.datastax.com/v2/clientIdSecrets' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>' \
 --data '{"roles": ["<roleId>"]}'

{
  "clientId":"zjCEYwRGWocLfQJHBNQxvorr",
  "secret":"SLR.cllL1YzfJDnl+YhUv5DMKlx8HaeMFTKjIJ4I6YdKB7w-K7U_+j-a9daWbbcp0uugXW,hb.3J2S0PPqDNhT6+oUiPYYaI+,xuwm2O97.ZpHcYvCsnlrTyl8w1pH-0",
  "orgId":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
  "roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
  "token":"AstraCS:zjCEYwRGWocLfQJHBNQxvorr:8709074baaf63e746cc5de52891e3a5ca88c73ae1fb7336652e9b59b9e69eff2",
  "generatedOn":"2021-04-30T19:38:26.147847107Z"
}

For the roleId, provide the relevant role’s id UUID value from a prior GET query, as shown in Getting existing roles in your organization. The API results will show the UUID for each role id.

Also refer to Generate token for client in the DevOps API.

Removing a token

When you remove a token, all users and roles assigned to that role will no longer have access.

Get a list of the available client IDs and secrets for your organization:

cURL command (/v2)
Result

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

{"clients":[
	{"clientId":"DkFtHKMhDQDuQtlExkSzwbya",
		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
		"generatedOn":"2021-02-22T17:09:58.668Z"},
	{"clientId":"eYSboCJaESiblJZnKZWMxROv",
		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
		"generatedOn":"2021-04-28T18:49:11.323Z"}
]}

Remove a token for a specific client ID:

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

Get a list of the available client IDs and secrets for your organization to confirm it was removed:

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

For more, see Revoke a token in the DevOps API.

What’s next?

You can now use your token to connect to the Astra DB APIs. See more about the available APIs:

BYOK AWS with DevOps API (Classic)

Encryption is a widely accepted mechanism to secure data against breaches. By default, DataStax Astra DB encrypts data, and cloud providers such as AWS or Google Cloud offer encryption solutions. However, you may want to further limit data access, because cloud providers have access to the keys and ultimately to the data.

To address this security concern, DataStax Astra DB allows you to associate a Customer Managed Key (one per region) that you defined in the AWS Key Management Service (KMS) with a Customer Key that you create in Astra DB.

In this topic, we’ll use these terms:

Bring Your Own Key (BYOK) refers to the overall capability.
Customer Managed Key (CMK) refers to a particular key type in AWS KMS.
Customer Key refers to the corresponding key association in Astra DB.

This BYOK feature:

Is available for Astra DB Classic users:
- On AWS
- Using the DevOps API
- Upon request - click the Chat icon in Astra Portal’s lower-right corner; ask the DataStax representative to enable BYOK for your organization
- See BYOK AWS with DevOps API (Classic)
Is not available with the Astra DB Free Plan. Using the Chat icon in Astra Portal, ask the DataStax representative about upgrading your organization to a paid plan so you can use BYOK and additional features.

For related details, see the Customer Keys API reference.

Introduction

Data encryption is defined as a process that transforms data into an encoded format. Once encoded, the data is incomprehensible without being decrypted. Data encryption is essential for organizations in all industries because it protects data from unauthorized access. When thinking of data encryption, two main scenarios are often considered:

Data at rest

Encrypting data while it is stored in the file storage in use.
Data in transit

Encrypting data while it travels through private or public networks.

BYOK allows customers to manage encryption for data at rest.

Benefits

BYOK allows you to take full control of the encryption keys when storing data in the cloud. AWS KMS provides protection against data breaches by alerting you when tampering occurs. In KMS, you can configure specific policies to adhere to compliance guidelines, such as auditing, key rotation, and access.

Setting up a corresponding Customer Key for an Astra DB database hosted in an AWS region enables the separation of:

The encrypted lock
The key that encrypts/decrypts data

This separation of lock and key is considered a best practice to secure data via encryption.

After setting up a Customer Managed Key (CMK) in your AWS account’s Key Management Service, use Astra Portal, or the DataStax DevOps API, to associate an existing AWS CMK with a Customer Key in Astra DB.

In Astra Portal, under Settings, see the Key Encryption section of Security Settings.

In addition to the console UI, BYOK provides DevOps API calls that allow you to programmatically:

Create a new association between a CMK (created in AWS KMS) and your Astra DB data, in a specific region.
List all Customer Keys that are associated with protecting the AWS-based Astra DB data for your organization.
List a specific Customer Key for an organization, based on the specified cloud provider (aws) & region combination.

Key deletion

Please contact DataStax Support if you need to delete a key from your Astra DB organization. If you agree, the DataStax Support team may perform the key deletion on your behalf. Once a registered association with an AWS KMS Customer Managed Key is deleted from your Astra DB organization, the default data encryption provided by Astra DB is used.

For users of Astra DB Classic, note that deleting a key would result in permanent loss of access to the data. This happens because Astra DB Classic uses block storage as opposed to blob storage, and block storage doesn’t support re-encryption on the fly.

This implementation of using block storage is also why Astra DB Classic cannot support key rotation. While you could share a key between an Astra DB Classic database and an Astra DB Serverless database, it’s not recommended. The goal of rotating the key on the Serverless data could result in the inadvertent loss of access to the Classic data.

Prerequisites

Create your Astra DB database using Astra Portal. In the case of this BYOK feature, create an AWS-based database, and choose one of the available regions to start.
Before submitting the DataStax DevOps API calls, set up a Customer Managed Key (one per region, as needed) in the AWS KMS, as outlined in this topic.
Create an application token to authenticate your service account in the DevOps API.
Ensure you have permission to create and view Customer Keys. See Roles and permissions.
Ensure that you know your Astra DB organization ID. When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

Multi-region support

The BYOK feature is supported in multi-region Astra DB environments; however, each region is encrypted using its own key. Keys cannot be shared across regions. For a given organization:

if you have an Astra DB database that spans multiple regions,
and if you’ve defined a Customer Managed Key in AWS or Google Cloud,
create a Customer Key in each (provider + region) combination.

Pricing

There is no additional cost to using BYOK with Astra DB. As noted previously, BYOK is not available with the Astra DB Free Plan.

Customer Managed Keys in AWS may incur a monthly fee, and a fee for use in excess of the AWS free tier. The fees are counted against the AWS KMS quotas for your AWS account. For details, see:

Roles and permissions

The following Astra DB roles can manage Customer Keys.

Organization Administrator
Database Administrator

To manage Customer Keys, your Astra DB account must have these permissions enabled.

org-cmk-read
org-cmk-write

AWS KMS console

Before you create a Customer Managed Key in the AWS Key Management Service (KMS), submit the following REST API call:

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/classic/provider/aws/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

The GET’s response includes the provider_id of the AWS account where DataStax will store your S3 buckets. Copy the ID number returned in the GET’s response. Then, when you configure your AWS KMS Customer Managed Key (see the steps below), you’ll specify this account number, and grant DataStax permission to access this account.

After authenticating into your AWS organization and account, search for, or navigate to, the Key Management Service (KMS).
On the KMS page, click the left sidebar link for Customer managed keys.
Click Create key.
Choose the Symmetric option for a single key, which will be used to encrypt and decrypt data for your Astra DB database in an Amazon S3 bucket. Click Next.
On Add labels, enter a memorable alias for your CMK, such as datastax-byok-cmk, and optionally provide a brief Description and user-defined Tags. Click Next.
On Define key administrative permissions, decide if you want to keep the option to Allow key administrators to delete this key. Also on this dialog, expand the down arrow in Key administrators section and select the relevant AWS accounts. Click Next.
On Define key usage permissions, decide which AWS accounts you want to authorize for the CMK’s usage. For now, skip the Other AWS Accounts option; there’s an option on the next screen to edit the in-progress Key policy definition. Click Next.
On the Review page, check the selected options, and then scroll through the generated Key policy. There are a couple manual edits to perform. Add the full section (see below) that starts with:
```
        {
            "Sid": "Allow an external account to use this KMS key",
            .
            .
            .
        }
```

Ensure that you have actions defined that are shown in the following example. Of course, your arn:aws:iam::… values will be different. The first sample ARN shown below is the account owner’s ID, and the second ARN in this sample is the ID of the AWS S3 storage account.

Again, to get the appropriate storage account ID value, if you haven’t already, use the following GET to retrieve the provider_id of the account that DataStax will use, and for which you’ll grant access permission.

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/classic/provider/aws/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

Make sure that your Key policy here in KMS, again in the section under "Allow an external account to use this KMS key", is using the intended S3 storage account ID’s arn:aws:iam::<storage-account-id>:role/creator value.

{
    "Version": "2012-10-17",
    "Id": "key-consolepolicy-3",
    "Statement": [
        {
            "Sid": "Enable IAM User Permissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111111111111:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow an external account to use this KMS key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::222222222222:role/creator"
            },
            "Action": [
                "kms:EnableKey",
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:ReEncryptTo",
                "kms:ReEncryptFrom",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow attachment of persistent resources",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::222222222222:role/creator"
            },
            "Action": [
                "kms:CreateGrant",
                "kms:ListGrants",
                "kms:RevokeGrant"
            ],
            "Resource": "*"
        }
    ]
}

In your edits, match the kms:… values in the Action:… section, under the Sid label that begins with "Allow an external account to use this KMS key". Ensure that your Key policy has the following actions defined. To use the KMS CMK with your Astra DB data, DataStax requires these eight actions:

            "Action": [
                "kms:EnableKey",
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:ReEncryptTo",
                "kms:ReEncryptFrom",
                "kms:DescribeKey"
            ]

You can copy/paste in those values (if not present already) into your KMS CMK’s Key policy textbox.

If you have questions, please contact us at Astra DB Product Management.

Also, in the Key policy section that starts with:

            "Sid": "Allow attachment of persistent resources",

Be sure to use the three actions shown in the sample below:

"Action": [
                "kms:CreateGrant",
                "kms:ListGrants",
                "kms:RevokeGrant"
            ],

When you are ready, click Finish.
On the AWS KMS Customer managed keys page, notice the alias name that you defined for your newly created CMK and its ID value.

Copy the ARN of the key you just created. That ARN can serve as the keyID that you’ll provide in the DevOps API /v2/kms/classic POST request payload

DevOps v2 API to manage Customer Keys

Submit DevOps API calls to create and view Customer Keys in your Astra DB organization. If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

For descriptions of the /v2/kms calls, see the sections below. For more, see the DevOps v2 API reference details.

By default, a POST /v2/kms call registers a new Customer Key for an Astra DB Serverless database. A POST v2/kms/serverless call performs the same request.

If you’re using Astra DB Classic on AWS, submit the POST payload to /v2/kms/classic.

To retrieve existing, registered keys used with Astra DB Serverless databases on AWS, use GET /v2/kms or /v2/kms/serverless.

For Astra DB Classic databases on AWS, use GET /v2/kms/classic.

Create a Customer Key for Astra DB Classic

Use the following POST to create a Customer Key in Astra DB Classic that will be associated with an existing Customer Managed Key in the AWS Key Management Service (KMS).

In the request payload, specify your Astra DB Classic organizationID, and the keyID of the Customer Managed Key that you created in AWS KMS, and the region. In each Astra DB Classic organization, there can be one Customer Key for a given cloud provider and region combination. A successful Customer Key creation returns 200 OK in the response.

When you log into Astra Portal, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

cURL command (/v2/kms/classic)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/kms/classic' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
  "orgId": "<organization-id>",
  "aws": {
    "keyID": "String - Resource name of the key",
    "region": "String - Region in which the key exists"
  }
}'

200 OK

Or one of the following:

400 Bad request.
403 The user is forbidden to perform the operation.
404 The specified resource was not found.
500 A server error occurred.

{
  "errors": [
    {
      "description": "string",
      "internalCode": "string",
      "internalTxId": "string"
    }
  ]
}

Get all Customer Keys in an Astra DB Classic organization

Retrieve all existing Customer Keys of an Astra DB Classic organization.

cURL command (/v2/kms/classic)
Result

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

When one or more keys are found for the organization, 
the 200 OK response contains, for each key:

[
  {
    "OrganizationID": "String - The ID of your organization",
    "CloudProvider": "aws",
    "KeyID": "String - The ID of the Customer Key",
    "Region": "String - The region in which the Customer Key is used"
  }
]

If there are no keys setup for the organization, 
the 404 response contains:

{
  "description": "Organization: <orgID> does not have 
                  any CMKs associated with it."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Get a single Customer Key in an Astra DB Classic organization

Retrieves a Customer Key in an Astra DB Classic organization for a given cloud provider & region combination. The provider value in this case should be aws.

cURL command (/v2/kms/classic)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/classic/provider/aws/region/<region>' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

When the key is found for the given provider and region, 
the 200 OK response contains:

{
  "orgId": "The ID of your organization",
  "provider": "aws": 
  { 
    "keyID": "The ID of the provider account where DataStax stores your data buckets",
    "region": "region-name"
  }
}

If there are no keys setup for the organization's provider 
and region combination, the 404 response contains:

{
  "description": "Could not find <provider> data in 
                  region <region> for organization <orgID>."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Get an array of Astra DB Classic Storage Cloud provider accounts

Retrieves a Customer Key in an Astra DB Classic organization for a given cloud provider & region combination. The provider value in this case should be aws.

The GET response also returns the provider ID of the storage account where your Amazon S3 buckets exist. If not done already, you can use this information to configure or modify (back in the AWS Key Management Service) your KMS Customer Managed Key, so that Astra DB has access to the key.

cURL command (/v2/kms/classic)
Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/classic/provider/aws/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

When the key is found for the given provider and region, 
the 200 OK response contains an array of:

[
  {
    "organization_id": "ID of your organization",
    "provider_id": "ID of the provider account
                   where DataStax stores your data buckets",
    "provider": "aws"
  }
]

If there are no keys setup for the organization's provider 
and region combination, the 404 response contains:

{
  "description": "Could not find <provider> data in 
                  region <region> for organization <orgID>."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

What’s next?

Managing access list

Use the DevOps API to add and remove addresses for your database access list. You can also enable and disable your access list.

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

The following roles use the application token to execute DevOps API queries:

Organization Administrator
Database Administrator

Prerequisites

Create an application token to authenticate your service account in the DevOps API.
Once you have authenticated your service account, you can add and remove IP addresses and CIDRs for your access list in the DevOps API.
You must have your access list on to be able to manage your access list via the DevOps API.

Adding addresses to your database access list

Check existing access lists within your organization or database to see which addresses are already on your access list(s):

Access lists are configured for each database within an organization. You must add each address to every database access list for which you want the address to have access.

cURL command (/v2): Get all access lists in organization
cURL command (/v2): Get access list in database
Result

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

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      }
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

For more, see Get all access lists for an organization and Get access list for a database in the DevOps API.

Get a template for your access list:

cURL command (/v2)
Result

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      }
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

For more, see Get template of access list in the DevOps API.

Complete your access list to submit.

Add your access list addresses:

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      [
        "address": "125.187.17.0/24",
        "enabled": true,
        "description": "Development"
      ]
    }'

For more, see Add addresses to access list for a database in the DevOps API.

Confirm the new addresses have been added to your access list:

cURL command (/v2)
Result

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      },
      {
        "address": "125.187.17.0/24",
        "enabled": true,
        "description": "Development"
      },
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

Replacing your existing access list

Check existing access lists within your organization or database to see which addresses are already on your access list:

cURL command (/v2): Get all access lists in organization
cURL command (/v2): Get access list in database
Result

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

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      }
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

For more, see Get all access lists for an organization and Get access list for a database in the DevOps API.

Submit your revised access list:

cURL command (/v2): Replace access list
cURL command (/v2): Update access list

curl --request PUT \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "addresses": [
          {
            "address": "125.187.17.0/24",
            "enabled": true,
            "description": "Development"
            "lastUpdateDateTime": "2021-01-21T17:32:28Z"
          }
        ],
        "configurations": {
          "accessListEnabled": true
        }
    }'

curl --request PATCH \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "addresses": [
          {
            "address": "125.187.17.0/24",
            "enabled": true,
            "description": "Development"
          }
        ],
        "configurations": {
          "accessListEnabled": true
        }
    }'

For more, see Replace access list for your database and Update existing fields in access list for database in the DevOps API.

Confirm the new addresses have been added to your access list:

cURL command (/v2)
Result

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      },
      {
        "address": "125.187.17.0/24",
        "enabled": true,
        "description": "Development"
      },
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

Deleting address or access lists

If you do not specify which addresses to delete, the entire access list is deleted.

When the entire access list is deleted, public access is no longer restricted.

Check existing access lists within your organization or database to see which addresses are already on your access list:

cURL command (/v2): Get all access lists in organization
cURL command (/v2): Get access list in database
Result

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

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      },
      {
        "address": "125.187.17.0/24",
        "enabled": true,
        "description": "Development"
      },
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

Delete an address from your access list:

cURL command (/v2): Delete addresses from access list
cURL command (/v2): Delete entire access list

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "addresses": [
          {
            "address": "125.187.17.0/24"
          }
        ]
    }'

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

Confirm the address no longer exists:

cURL command (/v2): Get all access lists in organization
cURL command (/v2): Get access list in database
Result

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

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

[
  {
    "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973",
    "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b",
    "addresses": [
      {
        "address": "137.187.23.0/24",
        "enabled": true,
        "description": "This address allows the database connections from the production environment.",
        "lastUpdateDateTime": "2021-01-21T17:32:28Z"
      }
    ],
    "configurations": {
      "accessListEnabled": true
    }
  }
]

For more, see Delete addresses or access list for database in the DevOps API.

What’s next?

Explore the DevOps API.

Managing multiple regions

Use the DevOps API to add or remove regions for your database.

The following roles use the application token to execute DevOps API queries:

Organization Administrator
Database Administrator

Prerequisites

Create an application token to authenticate your service account in the DevOps API.
Once you have authenticated your service account, you can add and removes regions in the DevOps API.

Adding a region to your database

You must have an existing database and payment method before you can add a new region. If you do not have a payment method for your database, you can add a payment method.

Check existing regions for your database:

cURL command (/v2)
Result

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

{
	"id": "1234-5678-91011121-3141",
	"name": "dc-1234-5678-91011121-3141",
	"tier": "Serverless",
	"cloudProvider": "GCP",
	"region": "europe-west1",
	"regionZone": "emea",
	"regionClassification": "standard",
	"capacityUnits": 1,
	"studioUrl": "http://path-to-studio:port",
	"grafanaUrl": "http://path-to-grafana:port",
	"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
	"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
	"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
	"secureBundleUrl": "http://s3-signed-bundle-url",
	"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
	"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
	"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
}

Add a new region to your database:

cURL command (/v2)

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "tier": "Serverless",
      "cloudProvider": "<cloudProvider>",
      "region": "<region>",
    }'

Confirm your region was added to the database:

cURL command (/v2)
Result

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

[
	{
		"id": "1234-5678-91011121-3141",
		"name": "dc-1234-5678-91011121-3141",
		"tier": "Serverless",
		"cloudProvider": "GCP",
		"region": "europe-west1",
		"regionZone": "emea",
		"regionClassification": "standard",
		"capacityUnits": 1,
		"studioUrl": "http://path-to-studio:port",
		"grafanaUrl": "http://path-to-grafana:port",
		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
		"secureBundleUrl": "http://s3-signed-bundle-url",
		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
	}
	{
		"id": "9364-1208-04716476-8536",
		"name": "dc-9364-1208-04716476-8536",
		"tier": "Serverless",
		"cloudProvider": "GCP",
		"region": "us-east1",
		"regionZone": "na",
		"regionClassification": "standard",
		"capacityUnits": 1,
		"studioUrl": "http://path-to-studio:port",
		"grafanaUrl": "http://path-to-grafana:port",
		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
		"secureBundleUrl": "http://s3-signed-bundle-url",
		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
	}

]

For more, see Invite a user to an organization in the DevOps API.

Delete a region from your database

The information displayed on the Connect page for your database is region specific.

Removing a region is not reversible. Proceed with caution.

Check existing regions for your database:

cURL command (/v2)
Result

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

[
	{
		"id": "1234-5678-91011121-3141",
		"name": "dc-1234-5678-91011121-3141",
		"tier": "Serverless",
		"cloudProvider": "GCP",
		"region": "europe-west1",
		"regionZone": "emea",
		"regionClassification": "standard",
		"capacityUnits": 1,
		"studioUrl": "http://path-to-studio:port",
		"grafanaUrl": "http://path-to-grafana:port",
		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
		"secureBundleUrl": "http://s3-signed-bundle-url",
		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
	}
	{
		"id": "9364-1208-04716476-8536",
		"name": "dc-9364-1208-04716476-8536",
		"tier": "Serverless",
		"cloudProvider": "GCP",
		"region": "us-east1",
		"regionZone": "na",
		"regionClassification": "standard",
		"capacityUnits": 1,
		"studioUrl": "http://path-to-studio:port",
		"grafanaUrl": "http://path-to-grafana:port",
		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
		"secureBundleUrl": "http://s3-signed-bundle-url",
		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
	}

]

Delete a region from your database:

cURL command (/v2)

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters/<datacenterID>/terminate' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

Confirm your region was removed from your database:

cURL command (/v2)
Result

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

{
	"id": "1234-5678-91011121-3141",
	"name": "dc-1234-5678-91011121-3141",
	"tier": "Serverless",
	"cloudProvider": "GCP",
	"region": "europe-west1",
	"regionZone": "emea",
	"regionClassification": "standard",
	"capacityUnits": 1,
	"studioUrl": "http://path-to-studio:port",
	"grafanaUrl": "http://path-to-grafana:port",
	"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
	"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
	"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
	"secureBundleUrl": "http://s3-signed-bundle-url",
	"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
	"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
	"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
}

For more, see Remove or uninvite a user from an organization in the DevOps API.

What’s next?

Learn more about using multiple regions.

Get private endpoints information with the DevOps API

Use the DevOps API to create, remove, and manage private endpoints.

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

The following roles can manage private endpoints:

Organization Administrator
Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

Prerequisites

Ensure you have permission to manage private endpoints.

To increase your security, consider restricting public access to your database using the access list.

Getting a list of private endpoint configurations

Check existing private endpoint configurations within your organization or database:

cURL command (/v2): Get all private endpoints in organization
cURL command (/v2): Get all private endpoints in database
Result

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

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

{
  "provider": "aws",
  "region": "us-east-1",
  "description": "Private Endpoint B",
  "organizationId": "string",
  "datacenterID": "string",
  "endpoints": [
    {
      "id": "string",
      "dateActivation": "1997-12-09T02:03:33.57Z",
      "dateDeactivation": "1997-12-09T02:03:33.57Z"
    }
  ]
}

Getting a list of private endpoint connections

Check existing private endpoint connections within your organization or database:

cURL command (/v2): Get all private endpoint connections in organization
cURL command (/v2): Get all private endpoint connections in database
cURL command (/v2): Get all private endpoint connections in specified region
Result

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

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

curl --request GET \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

If the database is only in a single region, datacenterID is your databaseID.

{
  "clusters": [
    {
      "databaseID": "string",
      "datacenters": [
        {
        "serviceName": "com.amazonaws.vpce.us-east-1.vpce-svc-1148ea04af491da11",
        "allowedPrincipals": [
          "arn:aws:iam::123456789012:role/admin"
        ],
        "datacenterID": "string",
        "endpoints": [
          {
            "endpointID": "vpce-svc-1148ea04af491da11",
            "description": "ecomm-team-billing-app",
            "status": "Accepted",
            "createdDateTime": "2009-11-10T23:00:00"
          }
          ]
        }
      ]
    }
  ]
}

What’s next?

Learn how to connect to AWS PrivateLink, Azure Private Link, or GCP Private Service Connect.

Explore Private endpoints in the DevOps API.

Connecting to AWS PrivateLink

To better protect your database connection, you can connect to a private endpoint using the Astra DB private endpoint. Private endpoints are available for only intra-region use. The region for your private endpoint in the AWS console and your Astra DB database must match.

For pricing related to using private endpoints, see Pricing and billing.

The following roles can manage private endpoints:

Organization Administrator
Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

For more about AWS PrivateLink, see AWS PrivateLink.

Prerequisites

Create your Astra DB database using Astra Portal.
Ensure you have permission to manage private endpoints.
Get your application token.

Only VPC owners can create resources such as VPC endpoints, subnets, route tables, and NACLs. Participants cannot view, modify, or delete resources that belong to other participants or the VPC owner. Thus a user cannot create resources, including a private endpoint, in a shared VPC that is owned by a different AWS account. To see which account owns your VPC, look at the Owner ID in the AWS Console. Example:

For more, see Work with shared VPCs - Amazon Virtual Private Cloud.

To increase your security, restrict public access to your database using the access list.

If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

Connect to your AWS PrivateLink endpoint

Get the allowed principal from your AWS account.
1. In your AWS console on the Identify and Access Management (IAM) Users page, select your user name from the available users.
2. Select the User ARN as your allowed principal. For example, arn:aws:iam::123456789012:root.

Enter the allowed principal for your private endpoints to Astra DB:

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "allowedPrincipals": [
        "arn:aws:iam::123456789012:role/admin"
      ]
    }'

To confirm your datacenter ID, see your database Dashboard or use the DevOps API to get all datacenter IDs within your database.

{
  "serviceName": "com.amazonaws.vpce.us-east-1.vpce-svc-1148ea04af491da11",
  "allowedPrincipals": [
    "arn:aws:iam::123456789012:role/admin"
  ]
}

Use the serviceName to create an endpoint in your AWS Console.

CLI
AWS console

Get a list of available services:

aws ec2 describe-vpc-endpoint-services

Results:

{
    "VpcEndpoints": [
        {
            "VpcEndpointId": "vpce-08a979e28f97a9f7c",
            "VpcEndpointType": "Interface",
            "VpcId": "vpc-06e4ab6c6c3b23ae3",
            "ServiceName": "com.amazonaws.us-east-2.monitoring",
            "State": "available",
            "PolicyDocument": "{\n  \"Statement\": [\n    {\n      \"Action\": \"*\", \n      \"Effect\": \"Allow\", \n      \"Principal\": \"*\", \n      \"Resource\": \"*\"\n    }\n  ]\n}",
            "RouteTableIds": [],
            "SubnetIds": [
                "subnet-0931fc2fa5f1cbe44"
            ],
            "Groups": [
                {
                    "GroupId": "sg-06e1d57ab87d8f182",
                    "GroupName": "default"
                }
            ],
            "PrivateDnsEnabled": false,
            "RequesterManaged": false,
            "NetworkInterfaceIds": [
                "eni-019b0bb3ede80ebfd"
            ],
            "DnsEntries": [
                {
                    "DnsName": "vpce-08a979e28f97a9f7c-4r5zme9n.monitoring.us-east-2.vpce.amazonaws.com",
                    "HostedZoneId": "ZC8PG0KIFKBRI"
                },
                {
                    "DnsName": "vpce-08a979e28f97a9f7c-4r5zme9n-us-east-2c.monitoring.us-east-2.vpce.amazonaws.com",
                    "HostedZoneId": "ZC8PG0KIFKBRI"
                }
            ],
            "CreationTimestamp": "2019-06-04T19:10:37.000Z",
            "Tags": [],
            "OwnerId": "123456789012"
        }
    ]

In the Amazon VPC console navigation pane, select Endpoints > Create Endpoint. The available serviceNames are listed in the Service Name section.

The status for your private endpoint should show pending acceptance.

Accept your AWS private endpoint connection with your serviceName:

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "endpointID": "vpce-svc-1148ea04af491da11",
      "description": "project-desc-dev-app"
    }'

{
  "datacenters": [
    {
      "serviceName": "com.amazonaws.vpce.us-east-1.vpce-svc-1148ea04af491da11",
      "allowedPrincipals": [
        "arn:aws:iam::123456789012:role/admin"
      ],
      "datacenterID": "string",
      "endpoints": [
        {
          "endpointID": "vpce-svc-1148ea04af491da11",
          "description": "project-desc-dev-app",
          "status": "Accepted",
          "createdDateTime": "2021-04-10T23:00:00"
        }
      ]
    }
  ]
}

Your AWS console will show that it is in the available state. For more, see Accept and reject endpoint connect requests.

Create a DNS entry for your private endpoint.
1. Download your secure connect bundle for the region of your choice. Get your latest secure connect bundle.
2. Unzip the secure connect bundle.
3. In config.json, copy the host key’s value.
4. In the AWS Console, create a CNAME record that points to the DNS name found in your VPC Endpoint details.
5. In the AWS Console, create a private zone to route traffic to your virtual IP using Amazon Route 53. Update the following domains to use REST and CQL:
  REST
  
  CQL
  efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.apps.astra.datastax.com
  
  efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.db.astra.datastax.com
  For more, see Configuring Amazon Route 53 to route traffic to an Amazon VPC interface endpoint.
6. In the AWS Console, create a DNS entry for the key host value and map it to your virtual IP address.

You can now connect to your private endpoint using your updated secure connect bundle. For more, see Drivers for Astra.

Remove a private endpoint

Delete a private endpoint from your Astra DB:

cURL command (/v2)

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints/<endpointID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

Remove your connection from AWS PrivateLink:
- CLI
- AWS Console
aws ec2 delete-vpc-endpoint-service-configurations --service-ids <serviceId>
In the Amazon VPC console navigation pane, select Endpoint Services.

For the service you want to delete, select Actions > Delete.

Select Yes, Delete to remove the connection.

What’s next?

AWS PrivateLink
DevOps API reference
Learn how to Manage access lists for public access.

Connect to Azure Private Link with the DevOps API

To better protect your database connection, you can connect to a private endpoint using the Astra DB private endpoint.

For pricing related to using private endpoints, see Pricing and billing.

The following roles can manage private endpoints:

Organization Administrator
Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

Prerequisites

Create your Azure private endpoint.
Ensure you have permission to manage private endpoints.

To increase your security, consider restricting public access to your database using the access list.

Connect to your Azure Private Link endpoint

Get the allowed principal from your Azure account. This is your Subscription ID.

Enter your Subscription ID as the allowed principal for your private endpoints to Astra DB:

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "allowedPrincipals": [
        "9cbbd094-fa31-490f-863d-897d01661681"
      ]
    }'

To confirm your datacenter ID, see your database Dashboard or use the DevOps API to get all datacenter IDs within your database.

{
  "serviceName": "test.a51y2a51-f9j4-4ad2-l863-67e5ac6g10m.westus2.azure.privatelinkservice",
  "allowedPrincipals": [
    "9cbbd094-fa31-490f-863d-897d01661681"
  ]
}

In your Azure Private endpoints, select Add.
1. Select your Subscription and then your Resource group for your project.
2. Enter your private endpoint name.
3. Select the region for your private endpoint. This region should match your Astra DB region.
4. Select Next: Resource.
5. Select Connect to an Azure resource by resource ID or alias as your Connection method.
6. Enter your serviceName as your Resource ID or alias.
7. Select Next: Configuration.
8. Select your Virtual network and Subnet from the menus.
9. Select Review + create and then select Create to finish creating your private endpoint.
For more, see Create a Private Endpoint using the Azure portal. Alternatively, you can create a private endpoint using Azure CLI.

Connect your Azure private endpoint connection:

Your endpointId is the Resource ID for your private link endpoint, which is available in your Azure console by selecting JSON View for your private link endpoint. For example, /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP_NAME/providers/Microsoft.Network/privateEndpoints/$ENDPOINT_NAME.

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "endpointID": "/subscriptions/a51y2a51-f9j4-4ad2-l863-67e5ac6g10m/resourceGroups/lab-resourceGroups/providers/Microsoft.Network/privateEndpoints/dev-poc",
      "description": "project-desc-dev-app"
    }'

{
  "datacenters": [
    {
      "serviceName": "test.a51y2a51-f9j4-4ad2-l863-67e5ac6g10m.westus2.azure.privatelinkservice",
      "allowedPrincipals": [
        "9cbbd094-fa31-490f-863d-897d01661681"
      ],
      "datacenterID": "string",
      "endpoints": [
        {
          "endpointID": "/subscriptions/a51y2a51-f9j4-4ad2-l863-67e5ac6g10m/resourceGroups/lab-resourceGroups/providers/Microsoft.Network/privateEndpoints/dev-poc",
          "description": "project-desc-dev-app",
          "status": "Accepted",
          "createdDateTime": "2021-04-10T23:00:00"
        }
      ]
    }
  ]
}

Create a DNS entry for your private endpoint. For more, see:
- What is Azure Private DNS?
- Quickstart: Create an Azure private DNS zone using the Azure portal.

Your Azure portal will show that it is in the approved state.

Remove a private endpoint

Delete a private endpoint from your Astra DB:

cURL command (/v2)

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints/<endpointID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

Remove your connection from your Azure portal:
- Azure console
- CLI
In the Azure VPC console, select Private Link Center > Private endpoints.

Select the checkbox beside the private endpoint you want to remove.

Select Remove.
Remove-AzPrivateEndpointConnection -Name myPrivateEndpointConnection1 -ResourceGroupName myResourceGroup -ServiceName myPrivateLinkServiceName

What’s next?

Azure Private Link documentation
DevOps API reference
Learn how to Manage access lists for public access.

Connect to Google Cloud Private Service Connect with the DevOps API

For pricing related to using private endpoints, see Pricing and billing.

The following roles can manage private endpoints:

Organization Administrator
Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

For more, see Google Cloud Private Service Connect.

Prerequisites

Create your Astra DB database using Astra Portal.
Ensure you have permission to manage private endpoints.
Get your application token.
From your Google Cloud Console, get your Project ID. For example, valiant-ocean-258751.
Create a Google Cloud Console network, subnetwork, and IP address for your private endpoint. For more, see Creating neworks.

To increase your security, restrict public access to your database using the access list.

If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

Connect to your Google Cloud Private Service Connect endpoint

Enter the Project ID as your allowed principal for your private endpoints to Astra DB:

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "allowedPrincipals": [
        "valiant-ocean-258751"
      ]
    }'

To confirm your datacenter ID, see your database Dashboard or use the DevOps API to get all datacenter IDs within your database.

{
  "serviceName": "projects/<projectID>/regions/<regionName>/serviceAttachments/<serviceAttachmentName>",
  "allowedPrincipals": [
    "valiant-ocean-258751"
  ]
}

Create the endpoint in your Google Cloud Console.
1. In the Google Cloud Console, go to Private Service Connect.
2. Select Connect endpoint.
3. Select Published service as the Target.
4. Enter the 'serviceName' from the DevOps API result as the Target service.
5. Enter a name for the Endpoint name.
6. Select your Network and Subnetwork for the endpoint.
7. Select an IP address for the endpoint.
8. Select Add endpoint.
The status for the endpoint will show as Accepted. This does not mean that the endpoint is ready for use and must be accepted in the Astra DB DevOps API.

Using the PSC Connection ID from your Google Cloud Console as your endpoint ID, accept your Google Cloud private endpoint connection:

cURL command (/v2)
Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
      "endpointID": "2755639674399101",
      "description": "project-desc-dev-app"
    }'
.sh[]

{
  "datacenters": [
    {
      "serviceName": "projects/<projectID>/regions/<regionName>/serviceAttachments/<serviceAttachmentName>",
      "allowedPrincipals": [
        "valiant-ocean-258751"
      ],
      "datacenterID": "string",
      "endpoints": [
        {
          "endpointID": "2755639674399101",
          "description": "project-desc-dev-app",
          "status": "Accepted",
          "createdDateTime": "2021-04-10T23:00:00"
        }
      ]
    }
  ]
}

Your Google Private Service Connect menu will show the private endpoint.

Create a DNS entry for your private endpoint.
1. Download your secure connect bundle for the region of your choice. Get your latest secure connect bundle.
2. Unzip the secure connect bundle.
3. In config.json, copy the host key’s value.
4. In the Google Cloud Console, create a private zone to route traffic to your endpoint IP. Update the following domains to use REST and CQL:
  REST
  
  CQL
  efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.apps.astra.datastax.com
  
  efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.db.astra.datastax.com
  For more, see Create a private zone.

You can now connect to your private endpoint using your updated secure connect bundle. For more, see Drivers for Astra.

Remove a private endpoint

Delete a private endpoint from your Astra DB:

cURL command (/v2)

curl --request DELETE \
  --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints/<endpointID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>'

In the Google Cloud Console, go to Private Service Connect.
Select the endpoint you want to remove.
Select Delete.

What’s next?

Private Service Connect
DevOps API reference
Learn how to Manage access lists for public access.