--- title: Get Started with the Edge Server REST API description: To get started with the Couchbase Edge Server REST API, you must specify the interface and authentication options using the Edge Server configuration file. pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbaselabs/docs-couchbase-lite-edge-server/edit/release/1.1/modules/rest-based-access/pages/rest-api-start.adoc xref: xref:couchbase-edge-server:rest-based-access:rest-api-start.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/couchbase-edge-server/current/rest-based-access/rest-api-start.html) # Get Started with the Edge Server REST API > 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)Interface To specify the interface for REST-based access to Edge Server, use the [interface](../configuration/edge-server-configuration.md#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's 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)Authentication For an overview of Couchbase Edge Server authentication mechanisms, see [Authentication](../configuration/authentication.md). You must specify authentication options to enable clients to connect securely to the REST API. ### [](#server-auth-with-tls)Server Authentication with TLS To enable TLS, you must create an asymmetric key-pair and a certificate containing the public key. Then set the certificate path and matching private-key path in the Edge Server configuration. These files can use Privacy-Enhanced Mail (PEM) format, which is ASCII (American Standard Code for Information Interchange) text, or Distinguished Encoding Rules (DER) format, which is binary. Add these to the [https](../configuration/edge-server-configuration.md#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)](#client-cert-authentication-mtls). | string | Example 1\. Enable server TLS ```json5 { https: { tls_cert_path: "./cert.pem", tls_key_path: "./private.key" } } ``` If you encrypted the private-key file, the server prompts you for its password on stdin. If unencrypted, restrict the file permissions so that only the server administrator can access it. ### [](#creating-a-self-signed-certificate)Create a Self-Signed Certificate > [!IMPORTANT] > In production you're 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 couchbase-edge-server --create-cert ``` The first argument can be one of two things: * The hostname clients use to reach the server. This becomes 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 fails. * 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\. You must include the `CN` attribute, as described above. The `` and `` arguments specify the paths for the certificate and key files the command creates. (If they already exist, the command overwrites them.) In this mode the program exits after creating the files, without starting the server. You can then add these filenames to the [https](../configuration/edge-server-configuration.md#https) property of your configuration file as described [previously](#server-auth-with-tls). The certificate uses a 4096-bit RSA key-pair and has a lifetime of one year. > [!IMPORTANT] > No client accepts 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 turn off validation. If another Edge Server is to sync with this server, you need to add the `pinned_cert` attribute to its replication configuration. See [Manage Replication with Edge Server](replication.md). If a Couchbase Lite application is to sync with this server, it needs a copy of the server's certificate, and set this as a pinned certificate in the replicator attributes. See the [Couchbase Lite](../../../couchbase-lite/current/index.md) documentation for details. ### [](#client-cert-authentication-mtls)Client Certificate Authentication (mTLS) To configure TLS client authentication (mTLS), add a [client\_cert\_path](../configuration/edge-server-configuration.md#https-client%5Fcert%5Fpath) property to the configuration file's [https](../configuration/edge-server-configuration.md#https) object, whose value is the path to the file containing the client CA certificate — that's, the master certificate that signs each client's certificate. The server's TLS handshake then requires a client certificate, and verifies that it's signed by the configured CA. Couchbase Edge Server derives the client's username from the Common Name (`CN`) field of the certificate. Example 2\. Enable mTLS client certificate authentication ```json5 { https: { tls_cert_path: "./cert.pem", tls_key_path: "./private.key", client_cert_path: "./ca.pem" } } ``` ### [](#usernames-and-passwords)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. > [!WARNING] > WARNING: _Never_ use basic authentication in production without TLS, or else clients transmit passwords in cleartext and packet-sniffers can capture them. The top-level [users](../configuration/edge-server-configuration.md#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 | > [!NOTE] > This file's schema is . The users file reads at startup. Changes take effect only after the server restarts. All HTTP requests require either Basic authentication or a client certificate, unless the top-level [enable\_anonymous\_users](../configuration/edge-server-configuration.md#enable%5Fanonymous%5Fusers) property sets to `true`. #### [](#passwords)Passwords For security, Couchbase Edge Server stores users' passwords in hashed form. A [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hash is represented as a 60-character string that starts with a `$`, 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 couchbase-edge-server --add-user ``` The command prompts you to enter the user's password (twice). Optional flags for this mode: * `--create` — the command creates the user file if it does not exist. * `--role ` — the command assigns the user the named role (`admin` or `replicate`). * `--password PASSWORD` — the command uses this password instead of reads it from stdin. (This is less secure since the shell history captures the password, and other processes using tools like `ps` can see it, but it's useful in scripts.) 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 htpasswd -nB ``` This prompts for the password, then outputs 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)User Roles The `roles` property of a user object adds privileges to that user account. Available user roles are: * `"replicate"` — allows user access `/_replicate` to start, stop, and monitor [replications](replication.md). * `"admin"` — allows everything. Currently no different from `"replicate"`. ## [](#examples)Examples Example 3\. 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 ./couchbase-edge-server --create-cert CN=localhost cert.cer key.pem ``` Example 4\. Create a users file and add a user This example creates a users file called `users.json` and adds a user called `seatuser`. ```sh ./couchbase-edge-server --add-user users.json seatuser --create ``` On running the command, you're prompted to enter and confirm a password for the new user. ## [](#see-also)See Also * [Edge Server REST API](rest-api-landing.md) * [Database Operations with Edge Server](database-operations.md) * [Document Access with Edge Server](document-access.md) * [Monitor Changes with Edge Server](changes-feed.md) * [Run Queries with Edge Server](queries-api.md) * [Manage Replication with Edge Server](replication.md) * [Edge Server Public REST API](../public-api-reference/index.md)