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

      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 are generated and displayed after a short period of time. 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 you misplace the key, you must generate a new one.
      4. 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.

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

      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.