A newer version of this documentation is available.

View Latest

Authorizing Users


    Sync Gateway provides the following REST APIs:

    • The Public REST API is used for client replication. The default port for the Public REST API is 4984.

    • The Admin REST API is used to administer user accounts and roles. It can also be used to look at the contents of databases in superuser mode. The default port for the Admin REST API is 4985. By default, the Admin REST API is reachable only from localhost for safety reasons.

    More information regarding the APIs themselves can be found in the API Reference section.

    Managing API Access

    The APIs are accessed on different TCP ports, which makes it easy to expose the Public REST API on port 4984 to endpoints while keeping the Admin REST API on port 4985 secure behind your firewall.

    If you want to change the ports, you can do that in the configuration file.

    • To change the Public REST API port, set the interface property in the configuration file.

    • To change the Admin REST API port, set the adminInterface property in the configuration file.

    The value of the property is a string consisting of a colon followed by a port number (for example, :4985). You can also prepend a host name or numeric IP address before the colon to bind only to the network interface with that address.

    As a useful special case, the IP address binds to the loopback interface, making the port unreachable from any other host. This is the default setting for the admin interface.

    Managing Guest Access

    Sync Gateway does not allow anonymous or guest access by default. A new server is accessible through the Public REST API only after you enable guest access or create some user accounts. You can do this either by editing the configuration file before starting the server or by using the Admin REST API. For more information, see Anonymous Access.

    Authorizing Users

    You can authorize users and control their access to your database by creating user accounts and assigning roles to users. This article focuses on how to authorize users to be able to access the Sync Gateway and their remote databases.


    You manage accounts by using the Admin REST API.This interface is privileged and for administrator use only. To manage accounts, you need to have some other server-side mechanism that calls through to this API.

    The URL for a user account is /databasename/_user/name, where databasename is the configured name of the database and name is the user name. The content of the resource is a JSON document with the following properties:

    • admin_channels: Lists the channels that the user is granted access to by the administrator. The value is an array of channel name strings.

    • admin_roles: The roles that the user is explicitly granted access to through the Admin REST API. It contains an array of role name strings.

    • all_channels: Like the admin_channels property, but also includes channels the user is given access to by other documents via a sync function. This is a derived property and changes to it are ignored.

    • disabled: This property is usually not included. if the value is set to true, access for the account is disabled.

    • email: The user’s email address. This property is optional.

    • name: The user name (the same name used in the URL path). The valid characters for a user name are alphanumeric ASCII characters and the underscore character. The name property is required in a POST request. You don’t need to include it in a PUT request because the user name is specified in the URL.

    • password: In a PUT or POST request, you can set the user’s password with this property. It is not returned by a GET request.

    • roles: Like the admin_roles property, but also includes roles the user is given access to by other documents via a sync function. This is a derived property and changes to it are ignored. It contains an array of role name strings.

    You can create a new user by sending a PUT request to its URL or by sending a POST request to /$DB/_user/.

    Anonymous Access

    A special user account named GUEST applies to unauthenticated requests. Any request to the Public REST API that does not have an Authorization header or a session cookie is treated as coming from the GUEST account. This account and all anonymous access is disabled by default.

    To enable the GUEST account, set its disabled property to false. You might also want to give it access to some channels. If you don’t assign some channels to the GUEST account, anonymous requests won’t be able to access any documents. The following sample command enables the GUEST account and allows it access to a channel named public.

    $ curl -X PUT localhost:4985/$DB/_user/GUEST --data \
       '{"disabled":false, "admin_channels":["public"]}'

    Admin Access

    When sending a change to Sync Gateway through the Admin REST API, the Sync Function is executed with admin privileges: calls to requireUser, requireAccess and requireRole are no-ops (i.e will always be successful).


    Roles are named collections of 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 /dbname/_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.