A newer version of this documentation is available.

View Latest



      About Sync Gateway Roles and their part in secure cloud-to-edge enterprise data synchronization.
      Here we introduce the concept of Roles and the part they play in assuring secure access control within Sync Gateway.

      Related concepts topics: Users | Roles | Channels | Revisions | Tombstones


      Roles are named collections of channels — see Channels.

      A User account can be assigned to zero or more roles. A user inherits the channel access of all roles it belongs to. This is very much like Unix groups, except that roles do not form a hierarchy.


      You access roles through the Admin REST API much like users are accessed, through URLs of the form /{tkn-db}/_role/{name}. Role resources have a subset of the properties that users do: name, admin_channels, all_channels.

      Roles have a separate namespace from users, so it’s legal to have a user and a role with the same name.

      Admin REST API

      You can assign a role to a user by sending a PUT request to /{tkn-db}/_user/{name} where db is the configured name of the database and name is the user name.

      The roles to assign to the user are specified in the admin_roles array.

      $ curl -vX POST "http://localhost:4985/mydatabase/_user/" -H "accept: application/json" -H "Content-Type: application/json" -d '{"name": "john", "password": "pass", "admin_roles": ["foo"]}'
      Configuration file

      A user can also be assigned to a role in the configuration file. This method is convenient for testing and to get started, otherwise it is generally recommended to use the Admin REST API for a programmatic behavior.

        "databases": {
          "mydatabase": {
            "users": { (1)
              "GUEST": {"disabled": true},
              "john": {"password": "pass", "admin_roles": ["foo"]}