Important Update: Please note that the V3 API will be deprecated soon and will no longer receive updates or support beyond its end-of-life date. To benefit from enhanced features and improved performance, we strongly recommend transitioning to our new V4 API. We’ve prepared a comprehensive guide detailing the steps on how to start working with V4 to make the process as smooth as possible for you.

Couchbase Capella offers a public API which enables administrators and developers to integrate and interact with the Control Plane using a variety of programming languages and platforms. The RESTful APIs are intended to enable customers to integrate with Couchbase Capella and perform operations such as:

    • Onboarding and offboarding users
    • Managing the lifecycle of a database
    • Monitoring a database

This blog post will show you how to utilize the Postman API client to interact with the Couchbase Capella Public API through the REST interface.

Note that this tutorial uses v3 of the Capella Public API. A revamped version of the API is in the works that may introduce some breaking changes. As such, we discourage you to use this version of the API in production deployments as we do not make guarantees on backwards compatibility with this version. However, we encourage you to evaluate the API and invite feedback on capabilities you would like to see in the new version of public API.


    • Postman is a great tool to interact with a REST API. In the remainder of this tutorial I assume you have installed Postman locally and it is ready for use. You can download it from
    • The next step is to download Couchbase Capella’s OpenAPI file from the Capella documentation website

    • You will also need to create an access key and a secret key to use the Public API. See instructions on how to set up your keys here.

Create a new Postman environment

In this step you will set up a new Postman environment (a set of variables you can use in your Postman requests). Couchbase Capella’s Public API will require your access and secret keys.

Make sure you name the variables exactly as follows:

    • accessKey containing your access key
    • secretKey containing your secret

It is probably best to set this new environment as the active one.

Import the OpenAPI definition

The next step is to import the OpenAPI definition file that you downloaded earlier. This will create a new Postman collection.

At this point, you have the collection and environment set up in Postman.

Configure Authentication

The Couchbase Capella Public API uses a Bearer token mechanism for authentication; each call to the Public API must be authenticated. You can find details on the two headers you must send with every request by consulting the official documentation on security headers.

To help you get started, we have a Postman pre-request script that generates the necessary headers based on your access and secret keys.

You must copy and paste this code into the Pre-request Script section of the collection. You can find more information about Pre-request scripts by visiting Postman’s documentation website.

At this point you are ready to run your queries. Next we will look at how to run some of the Public API queries.

Run queries

As a first example, let’s run the List Users call in the users folder.

When you run this query, you will notice that the response is empty despite the fact that you have users in your system. This is because the query parameters were assigned default values that are incorrect.

You must amend the following query parameters: page and perPage. In the following example, I will change the page to 1 and the perPage to 100 to get the expected result from the API.

That is it! Now you are ready to discover Couchbase Capella’s Public API. I hope you find some interesting ways to use it in your project.


Posted by Istvan Orban

Istvan Orban is the Principal Product Manager for Couchbase and lives in the United Kingdom. Istvan has a wide range of experience as a Full stack Software Engineer, Team leader and Devops Engineer. His main focus is security and Single Sign On. Istvan has led several large scale projects of his 20 year professional career.

Leave a reply