Download and use a Secure Connect Bundle (SCB) with Astra DB Classic

This page explains how to use the Secure Connect Bundle (SCB) for Astra DB Classic.

If you want to use the SCB with Astra DB Serverless, see the Download and use a Secure Connect Bundle (SCB) with Astra DB Serverless.

The Secure Connect Bundle (SCB) is a zip file containing security credentials and certificates required to establish a secure mutual TLS (mTLS) connection to an Astra DB database. The SCB establishes a secure external connection, and, within Astra DB, the protocol SNI over TCP is used to contact each node independently.

While you can use application tokens to securely connect to your Astra DB databases, some connections require keys, certificates, or other files that are available in the SCB.

SCB contents

The SCB is a zip file named secure-connect-DATABASE_NAME.zip. For multi-region databases, each SCB file name also includes the region name.

An SCB contains the following files:

ca.crt: DataStax’s Certificate Authority public certificate.
cert: A certificate, unique to the specific SCB.
key: A private key, unique to the specific SCB. Astra uses the key pair in the SCB to identify trusted clients through mutual TLS (mTLS) authentication.
cert.pfx: A PFX formatted archive containing the certificate and the private key.
config.json: A configuration file with information for securely connecting to the Astra DB instance associated with the SCB.
cqlshrc: A CQLSH profile containing CQL shell session settings.
identity.jks: A Java keystore file containing the cert and key files.
trustStore.jks: A Java keystore file containing the ca.crt.

SCB types

SCBs are database-specific, and databases can have multiple SCBs. You must use the SCB that corresponds to the specific database and region you want to connect to.

Astra DB Classic databases can have the following types of SCBs:

Default bundles	All databases have a default SCB for the default Astra DB domain and primary region, which is the first region you select when you create a database.
Regional bundles	Multi-region databases have separate SCBs for each region where the database is deployed.
External bundles	For Astra DB Classic databases with VPC peering enabled, you can download an external SCB for use within your VPC peering network.

Download the Secure Connect Bundle (SCB)

To download an SCB, you must get a download link from the Astra Portal, DevOps API, or Astra CLI.

For security purposes, the SCB download link expires after five minutes. Once the download link expires, you must generate a new download link.

Once downloaded, the SCB never expires.

Download SCBs with the Astra Portal

You can use the Astra Portal to download all SCB types for Astra DB Classic databases.

To use the Astra Portal to download an SCB for an Astra DB Classic database, do the following:

In the Astra Portal navigation menu, click Databases, and then click the name of your database.
Click Connect.
In the Database Essentials section, click Get Bundle.
In the Secure Connect Bundle Download dialog, select the region that you want to connect to with the SCB.

Multi-region databases have a different SCB for each region. Make sure you download the correct regional bundle.
For Astra DB Classic databases with VPC peering enabled, select Download External Secure Connect Bundle to get an SCB to use within your VPC peering network.
Click Download Secure Bundle, and then save the SCB as an archive (zip file).

Download SCBs with the DevOps API

You can use the DevOps API to download default bundles and regional bundles for Astra DB Classic databases. To download external bundles for VPC peering, see Download SCBs with the Astra Portal. For definitions of bundle types, see SCB types.

For more information about using the DevOps API, see Get started with the Astra DevOps API.

Send a POST request to the DevOps API secure bundle URL endpoint:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases/DATABASE_ID/secureBundleURL?all=true" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"
```
Provide the following:
- DATABASE_ID: The database ID of the database for which you want to download an SCB. If you need SCBs for multiple databases, you must send a separate request for each database.
- APPLICATION_TOKEN: An application token with the Organization Administrator role or Database Administrator role for the target database.
- all=true: For multi-region databases, this query parameter is required to fetch SCB download links for all regions.
Use the returned download URLs to download SCBs for the specified database:
```
{
  "downloadURL": "nifty.cloud.datastax.com:9092",   // Downloads the default bundle
  "downloadURLInternal": "internal-nifty.cloud.datastax.com:9092",
  "downloadURLMigrationProxy": "proxy-nifty.cloud.datastax.com:9092",
  "downloadURLMigrationProxyInternal": "proxy-nifty.cloud.datastax.com:9092",
  "datacenterID": "DATABASE_ID-1",    // Identifies the primary region.
  "region": "us-east-2",
  "cloudProvider": "AWS"
}
```
The response can contain multiple downloadURL keys:
- Default bundles: The main response object contains a downloadURL for datastax.com. You can use this link to download the default bundle configured for the default Astra DB domain and the database’s primary region (identified by datacenterID: "DATABASE_ID-1").
- Regional bundles: For multi-region databases, the response includes separate objects and download URLs for each region. Regions are identified by the datacenterID key where the primary region is "DATABASE_ID-1" and each secondary region is numbered sequentially as "DATABASE_ID-2", "DATABASE_ID-3", and so on.

Download SCBs with the Astra CLI

You can use the Astra CLI to download default bundles and regional bundles for Astra DB Classic databases. To download external bundles for VPC peering, see Download SCBs with the Astra Portal. For definitions of bundle types, see SCB types.

Use the Astra CLI download-scb command to download one SCB for a database:

astra db download-scb DB_ID -r REGION_NAME -d DIRECTORY_PATH

Replace the following:

DB_ID: Required argument specifying the ID of the target database. See Get your database ID.
-r REGION_NAME: Optional argument to download the SCB for a secondary region of a multi-region database.
-d DIRECTORY_PATH: Optional argument to download the SCB to a specific location. If unspecified, the command downloads the SCB to the directory where you run the command.

For more information, run astra help db download-scb or see the Astra CLI documentation.

SCB best practices

Treat the SCB the same way you would any other sensitive values, such as passwords or tokens.

The SCB contains sensitive information that establishes a connection to your database, including key pairs and certificates. For more information, see SCB contents.
Be careful when sharing connection details. SCB credentials grant access to your Astra DB database with ownership capabilities, such as modifying or deleting the database.
Always treat the SCB as a secret. For security purposes, practice responsible and secure credential management.
SCBs never expires after you download them. Make sure to clean up any downloaded SCBs when you no longer need them.
Use the SCB that corresponds to the specific database and region you want to connect to.

For example, if you want an application to connect to the region that is closest to your users, you must use the SCB for that region. For more information, see SCB types.
Provide the entire SCB zip file.

Don’t extract the SCB archive unless you require a specific file or value from within the SCB for a particular integration or configuration.

SCB use cases

To use an SCB, you typically provide the path to the SCB zip file in the application code that you use to connect to your Astra DB database.

The specific implementation depends on the application or integration you are using.

Here are some examples of components and integrations that support or require the use of SCBs:

Astra CLI
CQL and drivers
DSBulk
NoSQLBench
Integrations that use drivers or CQL to connect to your database.