Using the Public API

    +
    Get set up with an API Access token, and make your first REST interface call.

    To get started, the first thing that you will need is an API key.

    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, then the API call will be refused.

    Access and Secret keys

    1. 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. List of access keys in API keys management interface.

    2. Select Generate Key Generate key step.

    3. Enter a Key Name and select Submit. The keys will be generated and, after a short period of time, displayed. Key created - download this and take care to keep it safe.

      This is the only time the Secret key is shown. Make sure that you store it safely and securely. If, in the future, you misplace the key, you will need to generate a new one.
    4. Once you have stored the keys, select Close.

    Header values

    The header of each API call will need to 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.

    cbc_api_endpoint = '/v2/clouds'
    cbc_api_method = 'GET'
    cbc_api_secret_key = ‘my secret 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)
    }

    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.

    1. Enter the API key name to confirm that it is the one you wish to remove and then select Confirm.

    2. The API key is now removed and any calls to the API, using those Access and Secret Keys, will 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 listCapellas.py and createProject.py. Launch the application you want by running the file from a terminal.

    $ python listCapellas.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

    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 will be able to see the exact details for each API.