Database Security

March 23, 2025

+ 12

Using Sync Gateway’s Admin REST API to configure users and roles

Pre-3.0 Legacy Configuration Equivalents

This content describes configuration for Sync Gateway 3.0 and higher — for legacy configuration, see: Legacy Pre-3.0 Configuration

Introduction

We use the Admin REST API _user and _role endpoints to provision and manage sync gateway users through persistent configuration changes.

This content introduces the Create or Update a Role and Create or Update a User endpoints for convenience — see Database Security for a full description of the endpoints available.

It also includes a JSON-data model, you can use to build your request bodies. — see: Schema

Create or Update a Role

PUT /{db}/_role/{name}

If the role does not exist, create a new role otherwise update the existing role.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Application

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String
name required	The name of the role.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the role.

String

Body Parameter

Name	Description	Schema
Body optional	Properties associated with a role	Role1

Name

Description

Schema

Body
optional

Properties associated with a role

Role1

Responses

HTTP Code	Description	Schema
200	OK
201	Created
404	Resource could not be found	HTTP_Error

Example

Curl
HTTP

bash
Copy
curl --location --request PUT 'http://127.0.0.1:4985/travel25/_role/newrole' \ (1)
--header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \ (2)
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "newrole",
    "admin_channels": ["newrolechannel"]
}'

bash
Copy
PUT /travel25/_role/newrole HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk (2)
Content-Type: application/json
Content-Length: 67

{
    "name": "newrole",
    "admin_channels": ["newrolechannel"]
}

1	Add role `newrole` to the `travel25` database
2	Note we are using Basic Auth to authenticate to an existing RBAC user

Create or Update a User

PUT /{db}/_user/{username} (1)

1	where `{db}` is the Sync Gateway database and `{username}` is the name for the new user

If the user does not exist, create a new user otherwise update the existing user.

Required Sync Gateway RBAC roles:

Sync Gateway Architect
Sync Gateway Application

Parameters

Path Parameters

Name	Description	Schema
db required	The name of the database to run the operation against.	String
name required	The name of the user.	String

Name

Description

Schema

db
required

The name of the database to run the operation against.

String

name
required

The name of the user.

String

Body Parameter

Name	Description	Schema
Body optional	Properties associated with a user	User1

Name

Description

Schema

Body
optional

Properties associated with a user

User1

Responses

HTTP Code	Description	Schema
200	Existing user modified successfully
201	New user created
404	Resource could not be found	HTTP_Error

Example

Curl
HTTP

bash
Copy
curl --location --request PUT 'http://127.0.0.1:4985/travel25/_user/newuser' \ (1)
--header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \
--header 'Content-Type: application/json' \
--data-raw '{
    "password": "pass",
    "admin_channels": ["newrole"]
}
'

bash
Copy
PUT /travel25/_user/newuser HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk
Content-Type: application/json
Content-Length: 63

{
    "password": "pass",
    "admin_channels": ["newrole"]
}

1	Add user `newuser` to the `travel25` database

Schema

This section shows Sync Gateway’s database security configuration settings in schema format for convenience in constructing JSON models for use in the Admin REST API.

The configuration settings described here are provisioned through the Admin REST API — see as shown in Database Security.

{
   Role: {
      admin_channels: ["string"...],
      all_channels: ["string"...],
      collection_access: {
         {scopename...}: {
            {collectionname...}: {
               admin_channels: ["string"...],
               all_channels: ["string"...],
               jwt_channels: ["string"...],
               jwt_last_updated: "string"
            }
         }
      },
      name: "string"
   },
   User: {
      admin_channels: ["string"...],
      admin_roles: ["string"...],
      all_channels: ["string"...],
      collection_access: {
         {scopename...}: {
            {collectionname...}: {
               admin_channels: ["string"...],
               all_channels: ["string"...],
               jwt_channels: ["string"...],
               jwt_last_updated: "string"
            }
         }
      },
      disabled: true,
      email: "string",
      jwt_channels: ["string"...],
      jwt_issuer: "string",
      jwt_last_updated: "string",
      jwt_roles: ["string"...],
      name: "string",
      password: "string",
      roles: ["string"...]
   }
}

`Role`

Type: object
Description: Properties associated with a role

`Role.admin_channels`

Type: array
Description: The channels that users in the role are able to access for the default collection.

`Role.all_channels`

Type: array (readOnly)
Description: The channels that the role grants access to for the default collection.

These channels could have been assigned by the Sync function or using the admin_channels property.

`Role.collection_access`

Type: object
Description: A set of access grants by scope and collection.

`Role.collection_access.{scopename…}`

Type: object
Description: An object keyed by scope, containing a set of collections.

`Role.collection_access.{scopename…}.{collectionname…}`

Type: object
Description: An object keyed by collection name, defines access for the collection.

`Role.collection_access.{scopename…}.{collectionname…}.admin_channels`

Type: array
Description: A list of channels to explicitly grant to the user.

`Role.collection_access.{scopename…}.{collectionname…}.all_channels`

Type: array (readOnly)
Description: All the channels that the user has been granted access to.

Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

`Role.collection_access.{scopename…}.{collectionname…}.jwt_channels`

Type: array (readOnly)
Description: The channels that the user has been granted access to through channels_claim.

`Role.collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

Type: string (readOnly)
Description: The last time that the user's JWT roles/channels were updated.

`Role.name`

Type: string
Description: The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

`User`

Type: object
Description: Properties associated with a user

`User.admin_channels`

Type: array
Description: A list of channels to explicitly grant to the user for the default collection.

`User.admin_roles`

Type: array
Description: A list of roles to explicitly grant to the user.

`User.all_channels`

Type: array (readOnly)
Description: All the channels that the user has been granted access to for the default collection.

Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

`User.collection_access`

Type: object
Description: A set of access grants by scope and collection.

`User.collection_access.{scopename…}`

Type: object
Description: An object keyed by scope, containing a set of collections.

`User.collection_access.{scopename…}.{collectionname…}`

Type: object
Description: An object keyed by collection name, defines access for the collection.

`User.collection_access.{scopename…}.{collectionname…}.admin_channels`

Type: array
Description: A list of channels to explicitly grant to the user.

`User.collection_access.{scopename…}.{collectionname…}.all_channels`

Type: array (readOnly)
Description: All the channels that the user has been granted access to.

Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

`User.collection_access.{scopename…}.{collectionname…}.jwt_channels`

Type: array (readOnly)
Description: The channels that the user has been granted access to through channels_claim.

`User.collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

Type: string (readOnly)
Description: The last time that the user's JWT roles/channels were updated.

`User.disabled`

Type: boolean
Description: If true, the user will not be able to login to the account as it is disabled.

`User.email`

Type: string
Description: The email address of the user.

`User.jwt_channels`

Type: array (readOnly)
Description: The channels that the user has been granted access to through channels_claim.

`User.jwt_issuer`

Type: string (readOnly)
Description: The issuer of the last JSON Web Token that the user last used to sign in.

`User.jwt_last_updated`

Type: string (readOnly)
Description: The last time that the user's JWT roles/channels were updated.

`User.jwt_roles`

Type: array (readOnly)
Description: The roles that the user has been added to through roles_claim.

`User.name`

Type: string
Description: The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

`User.password`

Type: string
Description: The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

`User.roles`

Type: array (readOnly)
Description: All the roles that the user has been granted access to.

Access could have been granted through the sync function, roles_claim, or explicitly on the user under the admin_roles property.

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

Database Security

Introduction

Create or Update a Role

Parameters

Path Parameters

Body Parameter

Responses

Example

Create or Update a User

Parameters

Path Parameters

Body Parameter

Responses

Example

Schema

Role

Role.admin_channels

Role.all_channels

Role.collection_access

Role.collection_access.{scopename…​}

Role.collection_access.{scopename…​}.{collectionname…​}

Role.collection_access.{scopename…​}.{collectionname…​}.admin_channels

Role.collection_access.{scopename…​}.{collectionname…​}.all_channels

Role.collection_access.{scopename…​}.{collectionname…​}.jwt_channels

Role.collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

Role.name

User

User.admin_channels

User.admin_roles

User.all_channels

User.collection_access

User.collection_access.{scopename…​}

User.collection_access.{scopename…​}.{collectionname…​}

User.collection_access.{scopename…​}.{collectionname…​}.admin_channels

User.collection_access.{scopename…​}.{collectionname…​}.all_channels

User.collection_access.{scopename…​}.{collectionname…​}.jwt_channels

User.collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

User.disabled

User.email

User.jwt_channels

User.jwt_issuer

User.jwt_last_updated

User.jwt_roles

User.name

User.password

User.roles

Related Content

`Role`

`Role.admin_channels`

`Role.all_channels`

`Role.collection_access`

`Role.collection_access.{scopename…}`

`Role.collection_access.{scopename…}.{collectionname…}`

`Role.collection_access.{scopename…}.{collectionname…}.admin_channels`

`Role.collection_access.{scopename…}.{collectionname…}.all_channels`

`Role.collection_access.{scopename…}.{collectionname…}.jwt_channels`

`Role.collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

`Role.name`

`User`

`User.admin_channels`

`User.admin_roles`

`User.all_channels`

`User.collection_access`

`User.collection_access.{scopename…}`

`User.collection_access.{scopename…}.{collectionname…}`

`User.collection_access.{scopename…}.{collectionname…}.admin_channels`

`User.collection_access.{scopename…}.{collectionname…}.all_channels`

`User.collection_access.{scopename…}.{collectionname…}.jwt_channels`

`User.collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

`User.disabled`

`User.email`

`User.jwt_channels`

`User.jwt_issuer`

`User.jwt_last_updated`

`User.jwt_roles`

`User.name`

`User.password`

`User.roles`