Authentication & Authorization

How do I control access to my databases?

Access is granted per database. By default, all databases are only accessible to your account. You can give people read, write or admin privileges. Users are identified by either a Cloudant account name, an API key or are in a catch all "everyone else" group.

Where do I set permissions in the Dashboard?

Go into the database you want to change and click on the "Permissions" button. On this page you can edit who has what access and generate API keys to use.

What is a shared database?

A shared database is one that someone else has created and given you permission to access (this could just be read, or they might give you write or admin permission). It allows you to see (and possibly edit) the database contents without you having to duplicate the data into your account. Because they are "owned" by another user they are displayed differently in the Dashboard.

How do I share a database?

You can share DBs with other Cloudant users (by username) through the dashboard or the API. You can also make your DBs open to "everyone else" (i.e. the world) but we urge caution before making your DBs world-writable.

Can I manage access to my application programmatically?

Yes, you can. Set permissions by following a GET/modify/PUT sequence using:


For example, to find the current permissions for a database using curl, use a GET command:

curl https://<username><database>/_security

The expected response might be similar to:

  "_id": "security", 
  "cloudant": {
    "exampleuser1": [
This indicates that in addition to the database owner, there is also another account with the identifier "exampleuser1" that has read and write permission when accessing the database.

For the PUT, your JSON should have the form:


The nobody key is used to select what public access is granted, if any.

For example, to grant user1 permission to read and write, and to refuse any access to everyone else, you might use a curl command similar to the following:

curl https://<username><database>/_security -X PUT -H "Content-Type: application/json" -d '{"_id":"_security","cloudant":{"nobody":[],"user1":["_reader","_writer"]}}'

Deprecated: The earlier method of setting permissions by POSTing to the endpoint is now deprecated.

The response contains the following:

Property Description
ok True if the request was successful.
error If request was not successful, contains an error code.
reason If request was not successful, contains a human-readable description of why the error took place.
What is an API key?

API keys allow you to give access to a person or application without having to create a new Cloudant account. An API key consists of a randomly generated username and password, and appropriate access permissions. Once generated, an API key can be used in the same way as a normal user account, for example by granting read, write, or admin access permissions.

Important: IBM Cloudant Data Layer Local Edition ("Cloudant Local") does not support API Keys. For a similar capability, create "CouchDB" style users, as described in the IBM Knowledge Center.

Generating API keys is done either in the account dashboard page, under the permissions tab, or by making a POST to _api/v2/api_keys.

POST https://<username>

The response would be similar to:

  "password": "YPNCaIX1sJRX5upaL3eqvTfi", 
  "ok": true, 
  "key": "blentfortedsionstrindigl"
You must then assign the API key to a database (using a PUT request to https://<username><database>/_security), so that the key can be granted access permissions.

If you choose to generate an API key through the dashboard, remember to record the key name and password. These are both randomly generated, and cannot be retrieved if lost or forgotten.

Deprecated: The earlier method of generating API keys by POSTing to is now deprecated.

API key/password pairs are treated like any other user account. You can pass an API key to a call to share a database with it and assign permissions to it. They are meant for any situation where user accounts are not appropriate. Examples include having credentials in your source code and programmatically creating several accounts with different permissions. This request requires credentials.

The response contains the following properties:

Property Description
ok True if the request was successful.
error If request was not successful, contains an error code.
key API key.
password API password.
Do you offer SSL/HTTPS access? Does it cost more?

All accounts come with http and https access, at no extra cost.

How can I get your certificate bundle for my app?

If you need to bundle our wildcard certificates with your application you can get a copy of them by running

openssl s_client -connect -showcerts
Can I use CouchDB security features (_users database, security objects, validation functions) on Cloudant?

Yes you can. If you want to use the _users database you must first turn off Cloudant's own security for the roles you want to manage via _users. To do this you need to PUT a JSON document like the following to the _security endpoint of the database (for example https://<username><database>/_security):

  "couchdb_auth_only": true,
  "members": {
    "names": ["demo"],"roles":[]
  "admins": {...}

Browse the API Reference

← Back to FAQs