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

      +

      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

      • Curl

      • HTTP

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

      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

      • Curl

      • HTTP

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

      Related Content

      API Topics
      Reference
      Community

      Mobile Forum | Blog | Blog (Mobile) | Tutorials