Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Database Security

    March 23, 2025
    + 12

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

    Related topics: Overview | Bootstrap | Database | Database Security | Access Control | Import | Inter-Sync Gateway Replication

    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

    In 3.0 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}

    Use this convenience endpoint to upsert a Sync Gateway role.

    Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):

    • Sync Gateway Architect

    • Sync Gateway Application

    Parameters

    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    name
    required

    Role name, may contain any combination of the characters [a-z A-Z 0-9 - + . @ %], when creating a role any other characters must be percent encoded, see: https://en.wikipedia.org/wiki/Percent-encoding.

    When passing a role name in a URL path it must be escaped again using percent encoding for example if a role is created with the name "0|59", the '|' character must first be percent-encoded resulting in "0%7C59". When using the same role name in a URL path it must be percent-encoded a second time resulting in "0%257C59"

    string

    Body

    role
    optional

    The message body is a JSON document that contains the following objects.

    Role_model

    Responses

    HTTP Code Description Schema

    200

    200 - OK - Operation successful

    No Content

    201

    201 - OK - Create Operation successful

    No Content

    401

    401 - Unauthorized - Error validating credentials

    No Content

    Example

    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"]
}'
    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

    Use this method to create or update a user

    Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):

    • Sync Gateway Architect

    • Sync Gateway Application

    Parameters

    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    name
    required

    User’s name, may contain contain any combination of the characters [a-z A-Z 0-9 - + . @ %], when creating a user any other characters must be percent encoded, see: https://en.wikipedia.org/wiki/Percent-encoding.

    When passing a user name in a URL path it must be escaped again using percent encoding for example if a user is created with the name "0|59", the '|' character must first be percent-encoded resulting in "0%7C59". When using the same user name in a URL path it must be percent-encoded a second time resulting in "0%257C59"

    string

    Body

    user configuration data
    optional

    Provision the user configuration data in JSON format in the body

    User_model

    Responses

    HTTP Code Description Schema

    200

    200 - OK - Operation successful

    No Content

    201

    201 - OK - Create Operation successful

    No Content

    401

    401 - Unauthorized - Error validating credentials

    No Content

    Example

    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"]
}
'
    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: {
    name: "string",
    admin_channels: [
      "string"
    ],
    all_channels: [
      "string"
    ]
  },
  User: {
    name: "string",
    password: "string",
    admin_channels: [
      "string"
    ],
    admin_roles: [
      "string"
    ],
    all_channels: [
      "string"
    ],
    email: "string",
    disabled: false,
    roles: [
      "string"
    ]
  }
}

    Role

    object

    Use the role property to define a Sync Gateway role

    Role.name

    string

    Name of the role

    Role.admin_channels

    array

    Array of channel names the role allows access to

    Role.all_channels

    array

    Lists all the channels the role has access to including any assigned by the sync function.

    This is a derived property and changes to it are ignored.

    User

    object

    Definition of a Sync Gateway user

    Change initiates database restart

    User.name

    string

    The user name (the same name used in the URL path).

    The valid characters for a user name are alphanumeric ASCII characters and the underscore character.

    The name property is required in a POST request.

    You don't need to include it in a PUT request because the user name is specified in the URL.

    User.password

    string

    Password of the user.

    Mandatory, unless allow_empty_password=true.

    User.admin_channels

    array

    The channels that the user is able to access.

    User.admin_roles

    array

    An array of the roles this user is associated with.

    User.all_channels

    array

    Shows the channels the user can access, as granted by the sync function.

    This is a read-only property. Changes to it are ignored.

    User.email

    string

    Email address of the user.

    User.disabled

    boolean

    This property is usually not included.

    If the value is true, access for the account is disabled and the user will not be able to login.

    User.roles

    array

    Shows the roles this user is associated with by the Sync function.

    This is a read-only property. Changes to it are ignored.

    Related Content

    API Topics
    Reference
    Community

    Mobile Forum | Blog | Blog (Mobile) | Tutorials