Read Access



      Every user and role has a set of channels that they’re allowed to read. A user can only read documents that are in at least one of the user’s channels (or the channels of roles that user has.)

      After a user is granted access to a new channel, the changes feed incorporates all existing documents in that channel, even those from earlier sequences than the current request’s since parameter. That way the next pull request retrieves all documents to which the user now has access.

      Add Access

      User/role channel access can be assigned directly through the admin API, the configuration file or via the Sync Function when a document is updated. The Sync Function is the preferred method for granting access to channels programmatically.

      Sync Function

      Calling access(user, channel) grants a user access to a channel. This allows documents to act as membership lists or access-control lists.

      A typical example is a document that represents a shared resource (like a chat room or photo gallery). In the following example, a chat room is represented by a document with a type property set to chatroom. The channel_id property names the associated channel (with which the actual chat messages are tagged) and the members property lists the users who have access to that channel.

      function (doc) {
        if (doc.type == "chatroom") {
          access(doc.members, doc.channel_id);

      The access() function can also operate on roles. If a user name string begins with role: then the remainder of the string is interpreted as a role name. There’s no ambiguity here, because ":" is an illegal character in a user or role name.

      Because anonymous requests are authenticated as the user "GUEST", you can make a channel and its documents public by calling access with a username of GUEST.

      Configuration File

      A user can be granted access to a channel through the admin_channels property in the configuration file.

      Admin REST API

      A user can be granted access to a channel through the admin_channels property on the /{db}/user/{name} admin REST API endpoint.

      Revoke Access

      Revoking access to a channel can cause a user to lose access to documents, if s/he no longer has access to any channels those documents are in.

      However, the replicator does not currently delete such documents that have already been synced to a user’s device (although future changes to those documents will not be replicated.) This is a design limitation of Sync Gateway that may be resolved in the future.

      • A GET request to a document not assigned to one or more of the user’s available channels fails with a 403 error.

      • The _all_docs property is filtered to return only documents that are visible to the user.

      • The _changes property ignores requests (via the channels parameter) for channels not visible to the user.

      Inspect Read Access

      You can use the admin REST API to see what channels a user has access to. Issue an /{db}/_user/{name} request. Here’s an example of the response. The output shows that the user pupshaw has access to channels all and hoopy.

          "admin_channels": [
          "admin_roles": [
          "all_channels": [
          "name": "pupshaw",
          "roles": [

      The all_channels property of a user account determines which channels the user can access. Its value is derived from the union of:

      • The user’s admin_channels property, which is settable via the admin REST API.

      • The channels that user has been given access to by access() calls from sync functions invoked for current revisions of documents.

      • The all_channels properties of all roles the user belongs to, which are themselves computed according to the above two rules.


      By default, Couchbase Lite gets all the channels to which the configured user account has access. This behavior is suitable for most apps that rely on user authentication and the sync function to specify which data to pull for each user.

      Optionally, a Couchbase Lite "pull" replication can also specify a comma-separated list of channel names to receive documents from. In this case, the replication from Sync Gateway will only pull documents tagged with those channels. Client apps can use this ability to intelligently sync with a subset of the available documents from the database.

      Related Couchbase Lite content

      Java | Java (Android) | C# | Objective-C | Swift