Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Get Started with the Edge Server REST API

    March 30, 2025
    + 12
    To get started with the Couchbase Edge Server REST API, you must specify the interface and authentication options using the Edge Server configuration file.

    Interface

    To specify the interface for REST-based access to Edge Server, use the interface top-level property in the configuration file. This property is a string and may contain either or both of the following components:

    • An IP address

    • A port number, preceded by a colon (:)

    The interface property is optional. If the IP address is not specified, it defaults to 0.0.0.0, that is all interfaces. If the port number is not specified, it defaults to 59840.

    For testing, it may be useful to set the IP address to 127.0.0.1, which allows only clients on the same device to connect.

    Authentication

    You must specify authentication options to enable clients to connect securely to the REST API.

    Server Authentication with TLS

    To enable TLS, you must create an asymmetric key-pair and a certificate containing the public key. The Edge Server must then be told the location of the certificate and its matching private key. These are files that can be in PEM (ASCII) or DER (binary) format.

    Add these to the https property of the configuration file:

    Name Description Schema

    tls_cert_path
    required

    Path of file containing TLS server certificate.

    string

    tls_key_path
    required

    Path of file containing matching private key.

    string

    client_cert_path

    Path of file containing Certificate Authority (CA) certificate for clients. See Client Certificate Authentication (mTLS).

    string

    If the private-key file is encrypted, you will be prompted for its password on stdin. If unencrypted, ensure that the file is protected with strict permissions and only accessible by the server administrator to prevent unauthorized access.

    Create a Self-Signed Certificate

    In production you are recommended to use a certificate generated by a well-known Certificate Authority (CA) like Let’s Encrypt or Digicert.

    For convenience of development and testing, you can create a self-signed TLS server certificate by using the --create-cert flag, as follows.

    sh
    Copy
    couchbase-edge-server --create-cert <hostname.example.com> <CertFile> <KeyFile>

    The first argument can be one of two things:

    • The hostname by which the server will be reached; this will become the certificate’s X.509 CN attribute. This must match the hostname in the sync URL used by clients, or the client’s TLS handshake will fail.

    • One or more name=value pairs, separated by commas. Each name is an X.509 Distinguished Name or Subject Alternative Name component, such as OU or rfc822Name; see RFC 4519 and RFC 5280. The CN attribute is required, as described above.

    The <CertFile> and <KeyFile> arguments are the paths of the certificate and key files to be created. (If they already exist they will be overwritten.) In this mode the program exits after creating the files, without starting the server.

    You can then add these filenames to the https property of your configuration file as described previously.

    The certificate uses a 4096-bit RSA key-pair and has a lifetime of one year.

    No client will accept a self-signed certificate unless you turn off validation or explicitly tell it to trust that certificate. With the curl command, for example, you can add the --insecure flag to disable validation.

    If another Edge Server is to sync with this server, you will need to add the pinned_cert attribute to its replication configuration. See Manage Replication with Edge Server.

    If a Couchbase Lite application is to sync with this server, it will need a copy of the server’s certificate, and set this as a pinned certificate in the replicator attributes. See the Couchbase Lite documentation for details.

    Client Certificate Authentication (mTLS)

    To configure TLS client authentication (mTLS), add a client_cert_path property to the configuration file’s https object, whose value is the path to the file containing the client CA certificate — that is, the master certificate that signs each client’s certificate.

    The server’s TLS handshake will then require a client certificate, and verify that it’s signed by the configured CA. The client’s username will be taken to be the value of the Common Name (CN) field of the certificate.

    Usernames and Passwords

    Couchbase Edge Server also supports HTTP Basic authentication. To use HTTP Basic authentication, you need to specify the user names and their passwords.

    Basic authentication should never be used in production without TLS, or else passwords will be transmitted in cleartext and can easily be captured by packet-sniffers.

    The top-level users configuration property is a string containing the path to a JSON file of accounts. That file should contain a JSON object, whose keys are user names, and whose values are objects of the form:

    Name Description Schema

    password
    required

    bcrypt hash of password.

    string

    roles

    List of role-name strings.

    array
    This file’s schema is https://packages.couchbase.com/couchbase-edge-server/users_schema.json.

    The users file is read at startup. Changes will not take effect until the server is restarted.

    All HTTP requests require either Basic authentication or a client certificate, unless the top-level enable_anonymous_users property is set to true.

    Passwords

    For security, users' passwords are stored in hashed form. A bcrypt hash is represented as a 60-character string that starts with a $, usually something like $2y$05$, followed by base64-encoded data.

    The easy way to add a username and password is to use the --add-user CLI flag.

    sh
    Copy
    couchbase-edge-server --add-user <userfile> <username>

    You’ll be prompted to enter the user’s password (twice).

    Optional flags for this mode:

    • --create — the user file will be created if it doesn’t exist.

    • --role <role> — the user will be given the named role (admin or replicate).

    • --password PASSWORD — this password will be used, instead of being read from stdin. (This is less secure since the password will be captured in the shell history, and could be seen by other processes using tools like ps, but it’s useful in scripts.)

    Or, if you want to edit the users file by hand, you can create a bcrypt hash by running the htpasswd command, which is available from your Linux package manager, or pre-installed on macOS:

    sh
    Copy
    htpasswd -nB <username>

    This will prompt for the password, then output the username and hash separated by a :. Copy the part after the : and paste it into the new user’s password property value.

    User Roles

    The roles property of a user object adds privileges to that user account. Available user roles are:

    • "replicate" — allows user to access /_replicate to start, stop, and monitor replications.

    • "admin" — allows everything. Currently no different from "replicate".

    Examples

    Example 1. Create a self-signed certificate

    This example creates a self-signed certificate called cert.cer and a keyfile called key.pem. The CN attribute for the certificate is set to localhost.

    sh
    Copy
    ./couchbase-edge-server --create-cert CN=localhost cert.cer key.pem
    Example 2. Create a users file and add a user

    This example creates a users file called users.json and adds a user called seatuser.

    sh
    Copy
    ./couchbase-edge-server --add-user users.json seatuser --create

    On running the command, you are prompted to enter and confirm a password for the new user.

    See Also