Make an API Call with the Management API v3.0

how-to

How to make an API call with the Management API v3.0, formerly known as the Public API.

Deprecation Notice

The Management API v3.0 is deprecated and will be removed in future. Users of the Management API v3.0 must plan to migrate to the Management API v4.0. See Manage Deployments with the Management API v4.0.

Prerequisites

In order make an API call with the Management API v3.0, you must have an API key that was created for the Management API v3.0. API keys for the Management API v4.0 are not compatible with the Management API v3.0.

To create an API key for the Management API v3.0, see Get Started with the Management API v3.0.

HTTP Headers

Each API call must contain the following headers:

Authorization: Bearer <token>
Couchbase-Timestamp: <now>

Where:

`<token>`	is made up of the API access key, followed by a colon `:`, followed by a Base64-encoded HMAC SHA-256 hash.
`<now>`	is the number of milliseconds since 1970/01/01.

Base64-Encoded HMAC SHA-256 Hash

You must calculate the Base64-encoded HMAC SHA-256 hash from the API secret key and a message string. The message string is made up of the following:

The HTTP method being used, such as GET.
The endpoint being called, such as /v2/clouds.
The number of milliseconds since 1970/01/01.

There must be a newline character after each one of these, except the last. How the newline character is represented depends on the language used. In the following example, the newline character is escaped as \n:

GET\n/v2/clouds\n1614622252260

Make an API Call

You can use a client such as cURL or a native SDK call to make an API call with the Management API v3.0.

To make an API call:

Use the following base URL.

https://cloudapi.cloud.couchbase.com
Pass the HTTP Authorization and Couchbase-Timestamp headers.
If a request body is required, pass it in JSON format.

Alternatively, you can use a client such as Insomnia or Postman to explore the details of the REST API, generate code samples, and so on. The Management API v3.0 uses an OpenAPI v3 specification. To download the Management API v3.0 specification, go to the Management API Reference and find the link to the openapi.yaml file.

Examples

Calculate the HMAC SHA-256 Hash

To show how the Base64-encoded HMAC SHA-256 hash is calculated, here’s an example using Python 3.

<api-access-key> is the API access key.
<api-secret-key> is the API secret key.

import base64
import datetime
import hashlib
import hmac

cbc_api_endpoint = '/v3/clusters'
cbc_api_method = 'GET'
cbc_secret_key = '<api-secret-key>'
cbc_access_key = '<api-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)

List Databases

The following Bash script lists all databases available to the provided API key.

<api-access-key> is the API access key.
<api-secret-key> is the API secret key.

#!/bin/bash

ACCESS=<api-access-key>
SECRET=<api-secret-key>
BASEURL=https://cloudapi.cloud.couchbase.com

METHOD=GET
ENDPOINT=/v3/clusters
NOW=`date +%s000`

MESSAGE="$METHOD
$ENDPOINT
$NOW"

HASH=`echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64`

curl -X $METHOD "$BASEURL$ENDPOINT" \
  -H "Authorization: Bearer $ACCESS:$HASH" \
  -H "Couchbase-Timestamp: $NOW"

The response is a JSON object similar to the following.

Result

{
  "cursor": {
    "pages": {
      "page": 1,
      "next": 2,
      "last": 6,
      "perPage": 10,
      "totalItems": 58
    },
    "hrefs": {
      "first": "http://<BASEURL>/public/v3/clusters?page=1&perPage=10",
      "last": "http://<BASEURL>/public/v3/clusters?page=6&perPage=10",
      "next": "http://<BASEURL>/public/v3/clusters?page=2&perPage=10"
    }
  },
  "data": {
    "items": [
      {
        "environment": "hosted",
        "id": "<redacted>",
        "name": "a1-saicharan-loyaladalovelace",
        "projectId": "<redacted>"
      },
// ...
      {
        "environment": "hosted",
        "id": "<redacted>",
        "name": "bravewilliamwulf",
        "projectId": "<redacted>"
      }
    ],
    "tenantId": "<redacted>"
  }
}

Note that this response contains cursor information, showing the pagination of the results.

Next Steps

For a full reference guide, see Management API v3.0 Reference.