Download and use a Secure Connect Bundle 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 Astra DB Serverless documentation.

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.

Secure Connect Bundle 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 DB 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.

Secure Connect Bundle 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

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 Secure Connect Bundle 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, select 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 Secure Connect Bundle types.

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 Secure Connect Bundle types.

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

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

Replace the following:

DB_NAME: Required argument specifying the name of the target database.
-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.

Secure Connect Bundle 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 Secure Connect Bundle 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 Secure Connect Bundle 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.

Secure Connect Bundle use cases

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

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