A newer version of this documentation is available.

View Latest

Access()

      +

      Enabling Sync Gateway data access

      Related Topics:    access()   |   channel()   |   expiry()   |   requireAccess()   |   requireAdmin()   |   requireRole()   |   requireUser()   |   role()   |   throw()

      Function

      access(username, channelname)

      Purpose

      Use the access() function to grant a user access to a channel.

      Arguments

      Argument Description

      username

      Must be a string identifying a user, or an array of strings identifying multiple users; the function is applied to each user in the array.

      If the value resolves to null the function result is a no-op.

      channels

      Must be a string identifying a channel name, or an array of strings to specify multiple channel names (for example: (['channel1', 'channel2']); the function is applied to each element in the array.

      If the value resolves to null the function result is a no-op.

      As a convenience, the resolved value of either argument may be null or undefined, in which case nothing happens.

      Context

      You can invoke this function multiple times from within your Sync Function.

      Prefix the username argument value with role: to apply this function to a role rather than a user. This grants access to the specified channel(s) for all users assigned that role.

      The effects of all access calls by all active documents are effectively combined in a union, so if any document grants a user access to a channel, that user has access to the channel.

      You can use the all channels wildcard ('*') to grant the user access to all documents in all channels.

      Use

      Example 1. access(username, channel)

      This example shows some valid ways to call access():

      access ("jchris", "mtv"); (1)
      access ("jchris", ["mtv", "mtv2", "vh1"]); (2)
      access (["snej", "jchris", "role:admin"], "vh1"); (3)
      access (["snej", "jchris"], ["mtv", "mtv2", "vh1"]); (4)
      access (null, "hbo");  (5)
      access ("snej", null);
      1 Allow access of single channel to single user
      2 Allow access of multiple channels to single user
      3 Allow access of single channel to multiple users
      4 Allow access of multiple channels to multiple users
      5 The null arguments mean these are treated as no-ops
      If you invoke the access() function multiple times to grant the same user access to the same channel, you could see negative performance effects, such as large fetches or request timeouts.