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.
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.
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.
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:
$ 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 |
$ 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 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
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.