Using the Public API

Get set up with an API Access token to make your first REST interface call.

You need an API key to get started.

API Keys

Couchbase Capella Public API uses a Bearer token mechanism for authentication; each call to the Public API has to authenticate.

To use the Bearer token mechanism with the Couchbase Capella Public API, it is first necessary to obtain Access and Secret keys — this is done within Couchbase Capella UI. These keys are specific to your account in Couchbase Capella and also control authorization for API operations. For example, if you use Access and Secret keys with the Public API to create a cluster from a Couchbase Capella account that itself cannot create a Cluster, the API call is refused.

Access and Secret keys

After logging into Couchbase Capella, select API keys. You will see the list of API keys. Note: Only the access key is shown. The Secrets key is only seen during key creation.
Select Generate Key
Enter a Key Name and select Submit. The keys are generated and displayed after a short period of time.

This is the only time the Secret key is shown. Make sure that you store it safely and securely. If you misplace the key, you must generate a new one.
When you have stored the keys, select Close.

Header values

The header of each API call must contain the following:

'Authorization': 'Bearer' + token
'Couchbase-Timestamp' : 'now'

Where
token =  Access key + ':' + Base 64 encoded Hmac sha256 hash
now = The number of milliseconds since 1970/01/01

The Hmac sha256 hash uses the Secret Key with a message string made up from the following:

HTTP method being used e.g. GET
Endpoint being called e.g. /v2/clouds
The number of milliseconds since 1970/01/01
There needs to be a newline character after each one of these, but not the last one.

Example complete message string

GET\n/v2/clouds\n1614622252260

To show how the Base 64 encoded Hmac sha256 hash is calculated, here’s an example using Python 3.

import base64
import datetime
import hashlib
import hmac

cbc_api_endpoint = '/v2/clouds'
cbc_api_method = 'GET'
cbc_secret_key = 'my secret key'
cbc_access_key = 'my access key'

# Epoch time in milliseconds
cbc_api_now =  int(datetime.datetime.now().timestamp() * 1000)

# Form the message string for the Hmac hash
cbc_api_message= cbc_api_method + '\n' + cbc_api_endpoint + '\n' + str(cbc_api_now)

# Calculate the hmac hash value with secret key and message
cbc_api_signature = base64.b64encode(hmac.new(bytes(cbc_secret_key, 'utf-8'), bytes(cbc_api_message,'utf-8'), digestmod=hashlib.sha256).digest())

# Values for the header
cbc_api_request_headers = {
   'Authorization' : 'Bearer ' + cbc_access_key + ':' + cbc_api_signature.decode() ,
   'Couchbase-Timestamp' : str(cbc_api_now)
}

print (cbc_api_request_headers)

Revoking access

Once Access and Secrets keys are being used to authenticate, they are valid until being revoked. To do this, login into Couchbase Capella, select ‘API Keys’ and then choose the trash icon on the row of the Key that you want to revoke.

Enter the API key name to confirm that it is the one you wish to remove and then select Confirm.
The API key is now removed. Any calls to the API using those Access and Secret Keys now fail.

Example Code

This is a sample application to demonstrate using Couchbase Capella Public API to automate operations. The application lists the Capella connections.

Prerequisites

The following pieces need to be in place in order to run the application:

Access and Secret Keys for authentication to the API.
Python 3.8 or greater, or supported Golang.

Running the application

To download the application you can either download the archive or clone the repository:

git clone https://github.com/couchbasecloud/rest-api-examples.git

Now, choose whether to follow along with the Python or the Go example:

Python
Go

Change Directory

$ cd rest-api-examples/python

The application uses several Python libraries that need to be installed. These are listed in requirements.txt and can be automatically loaded using the pip command:

$ pip install -r requirements.txt

Set environment variables for the base URL, and access and secret keys. Replace <> with your values for secret and access keys:

$ export cbc_api_url='https://cloudapi.cloud.couchbase.com'

$ export cbc_secret_key='<>'

$ export cbc_access_key='<>'

The application is split into several modules, such as getClouds.py and createProject.py. Launch the application you want by running the file from a terminal:

$ python getClouds.py

You will see a list of clouds in a table format, rather like this example

Name	Provider	Region	ID
A Capella	aws	us-east-2	daeca03d-f6d8-4666-9b3e-3b913ec2da80

Name

Provider

Region

A Capella

aws

us-east-2

daeca03d-f6d8-4666-9b3e-3b913ec2da80

Change Directory

$ cd rest-api-examples/go/examples

The Go examples repo provides a tiny http client wrapper which generates request headers using access/secret keys. Generated headers are required to interact with the API.

Environment Variables

Environment variables provided below must be set in order to use API Client. You can use the godotenv package to temporarily populate it using the .env file. .env is located in ./examples directory.

In order to get ACCESS/SECRET (or in other API key) you need to have access to the Couchbase Capella UI, and have an admin user who has access to manage the tenant.

ACCESS_KEY=
SECRET_KEY=
BASE_URL=https://cloudapi.cloud.couchbase.com

Usage

Executing the command from ./examples directory should list all tenant projects.

godotenv -f .env go run ./get '/v2/projects'

The response of each example consists of status code and body.

A full list, and instructions, is included in the Go repo’s README.md.

Additional Information

The REST API guide can be found here, along with links to the fully documented openapi.yaml file. By importing the yaml file into tools such as Postman, Insomnia or similar, you can see the exact details for each API.