A newer version of this documentation is available.

View Latest

How to Create a Role

      +

      How to create a Sync Gateway Role for secure access control in cloud-to-edge enterprise data synchronization.
      Sync Gateway Roles are a key part of a flexible approach to data routing and access control.

      Related topics: Create Role | Create User | Add Role to User | Allow Access | Verify Access | Write Access

      Related Concepts: Roles

      Provisioning

      The creation of roles is optional. It depends on the use case whether there is a need to logically group users.

      You can create and-or manage roles using the following options

      • Admin REST API:
        Roles are created via the Sync Gateway Admin REST API — see: Admin REST API.

      • File-based Configuration Properties [1]

        Note To use this option in v3.x, you must use the -disable_persistent_config CLI option.

        Configure roles in the Legacy Configuration Properties file.

      Note that removing a role effectively revokes access to the channel that role is associated with and may mean users will lose access to required documents.

      Example 1. How to Create a Role
      • Admin REST API

      • File-based Configuration Properties

      This is the default recommended option starting 3.0..

      Create a new role using the /{tkn-db}/_role/ endpoint.

      $ curl -vX POST "http://localhost:4985/mydatabase/_roles/" -H
      "accept: application/json" -H "Content-Type: application/json" -d
      '{"name": "Edge1", "admin_channels": ["channel1", "channel3"]]}' (1)
      1 Here we add the Edge1 role.

      Create roles by hardcoding them in the Legacy Pre-3.0 Configuration. This method is convenient for testing and to get started. It is recommended to use the REST API for production systems.

      {
        "databases": {
          "mydatabase": {
            "roles": { (1)
              "Edge1": {"admin_channels": ["channel1", "channel3"]}, (2)
              "Edge2": {"admin_channels": ["channel2", "channel3"]},
              "GUEST": {"disabled": true}
            }
          }
        }
      }
      1 databases.$db.users
      2 Here we add the Edge1 role.

      :include-related!