You are viewing the documentation for a prerelease version.

View Latest

Secure API Access


    Sync Gateway REST API Access
    Shows how to access Sync Gateway APIs

    Related REST API topics: Public REST API | Admin REST API | Metrics REST API


    Sync Gateway provides secure access to its REST APIs, namely the:

    Each REST API is accessed through a different, user-specifiable, TCP port. This makes it easy to control their physical exposure, perhaps to keep the Admin REST API secure behind your firewall.

    Sync gateway 3.0 BETA brings additional optional but default layers of security through enforcing TLS encryption for all API traffic and Couchbase Server Role-Based Access Control (RBAC) authorization and authentication for all Admin and Metrics API users.

    RBAC user authentication enables Secure Administration of sync gateway clusters. This is critical in cloud native deployments. It provides secure and fine-grained access control.


    TLS is enforced by default for all Couchbase Server connections in 3.0 BETA. For more on TLS, see: enforcing TLS encryption.

    Secure Administration

    Secure Administration is on by default.

    In order to submit Admin or Metrics REST API requests you should create specific Couchbase Server users for that purpose. You will then provide a valid set of Couchbase Server credentials for these RBAC-users in each API request.

    Authenticated users will have access to Admin and-or Metrics API functionality, application data and configuration settings.

    The access-level will depend on the selected role. Currently available roles may vary depending on the Couchbase Server release version — see Table 1.

    Table 1. Sync gateway role availability by release
    Couchbase Server ENTERPRISE EDITION Versions COMMUNITY EDITION Versions

    Available Roles

    6.1 - 7.0

    5.5 - 6.0


    All Versions

    sync-gateway role















    Full Admin





    For more on creating Couchbase Server users see the Couchbase Server content here Server — Manage Users and Roles.

    Secure Administration Opt-out

    You can choose to disable Secure Administration by using these bootstrap configuration settings or CLI flags:

    LDAP Authentication

    Authentication against an external system such as LDAP is possible through Couchbase Server.

    However, this can increase the risk of performance and or connection issues — for more on this see the Couchbase Server documentation LDAP Users and Authentication

    Port Configuration

    You can change the ports used for any of the interface types by editing its bootstrap configuration property, for example, api.admin_interface — as shown in Example 1 — and restarting the sync gateway node. The default ports are shown in Table 2.

    Example 1. Configuring ports
    • Admin

    • Metrics

    • Public

      api: {
        "admin_interface": "http://localhost:4985", (1)
        "admin_interface_authentication": true,
        // ... additional group properties
      api: {
        "metrics_interface": "http://localhost:4986", (1)
        "metrics_interface_authentication": true,
        // ... additional group properties
      api: {
        "public_interface": "http://localhost:4984", (1)
        // ... additional group properties
    1 The value of the interface property is a string consisting of a colon followed by a port number (for example, :4985). You can also include a host name or numeric IP address before the colon to bind only to that network interface, as shown here

    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.

    Network Port Requirements

    Sync Gateway uses specific ports for communication with the outside world, mostly Couchbase Lite databases replicating to and from Sync Gateway — see Table 2 for details.

    Table 2. Sync Gateway Network Port Requirements
    Port Description


    Public port. External HTTP port used for replication with Couchbase Lite databases and other applications accessing the REST API on the Internet.

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


    Admin port. Internal HTTP port for unrestricted access to the database and to run administrative tasks.

    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.


    Metrics port. By default 4986 is the internal HTTP port designated for providing access to Sync Gateway’s Metrics REST API. Like the admin port, it is bound to by default.

    The Metrics REST API returns Sync Gateway metrics, in JSON and-or Prometheus-compatible formats, for performance monitoring and-or diagnostic purposes,

    For more on configuration see api.admin_interface