With the Sync Gateway API, you can authenticate on the client side as a specific user to replicate the data this user has access to. In the case of basic authentication, the user must already exist in the Sync Gateway database. There are two ways to create users:

  • In the configuration file under the users field.
  • On the Admin REST API.

To provide a login and sign up screen, you must setup an app server that handles the user creation accordingly as the admin port (4985) is not publicly accessible. In this tutorial, you’ll learn how to:

  • Use the Admin REST API to create a user.
  • Setup an App Server with Node.js to manage the users.
  • Design a Login and Sign up screen in a sample Android app to test your App Server.

Getting started

Download Sync Gateway and unzip the file:


For this tutorial, you won’t need a configuration file. For basic config properties, you can use the command line options. The binary to run is located in ~/Downloads/couchbase-sync-gateway/bin/. Run the program with the --help flag to see the list of available options:

For this tutorial, you will specify the dbname, interface, pretty and url:

To create a user, you can run the following in your terminal:

NOTE: The name field in the JSON object should not contain any spaces.

This should return a 201 Created status code. Now, login as this user on the standard port:

The response will contains a Set-Cookie header and the user’s details in the the body.

All of the Couchbase Mobile SDKs have a method to specify a user’s name and password for authentication so you will most likely not have to worry about making that second request to login.

App Server

In this section, you’ll use the /_user Admin REST API endpoint publicly to allow users to sign up through the app.

You’ll use the popular Express module to handle the request to create a user and the request module to proxy all other traffic to Sync Gateway.

Install the following Node.js modules:

Open a new file server.js and add the following:

Here’s what is happening step by step:

  1. Instantiate a new instance of express and use the bodyParser middleware only if the path matches signup. Indeed, for all other requests proxied to Sync Gateway you need the raw request body.
  2. Handle the /signup requests and use the request module to create the user on the admin port.
  3. Proxy all other requests to Sync Gateway.
  4. Start the Node.js web server on port 8000.

From now on, you will use the url below to create users through the app and kick off push/pull replications:


Create another user to test that everything is working as expected:

And to login as this user:

In the next section, you will create a simple Android app with a login and signup screen to test those endpoints.

Android app

Open Android Studio and select Start a new Android Studio project from the Quick Start menu.

Name the app SmartHome, set an appropriate company domain and project location, and then click Next:

On the Target Android Devices dialog, make sure you check Phone and Tablet, set the Minimum SDK to API 22: Android 5.1 (Lollipop) for both, and click Next:

On the subsequent Add an activity to Mobile dialog, select Add Blank Activity and name the activity Welcome Activity:

To build the signup and login functionalities you will use two dependencies:

  • Android Design Support Library: to have input text components that follow the Material Design spec.
  • OkHttp: to handle the POST requests to /signup and /smarthome/_session.

In build.gradle, add those dependencies:

In activity_welcome.xml, add the following LinearLayout inside of the existing RelativeLayout:

Notice that both buttons have an onClick attribute. Move the mouse cursor on one of the methods and use the alt + enter > Create openLoginActivity(view) shortcut to create that method in WelcomeActivity:

Do the same for the Sign Up button.

Next, create two new classes and XML layouts using the Blank Activity template. One should be called Login and the other SignUp:

Back in the openLoginActivity and openSignUpActivity methods, add the following explicit intents:

Change the parent class of Login.java and SignUp.java from AppCompatActivity to Activity.

In res/values/styles.xml (v21), change the parent theme to Theme.AppCompat.Light.DarkActionBar.

Open activity_sign_up.xml and add the following inside of the RelativeLayout tag:

Now run the app and select the Sign Up button, you will see the Material Design EditText elements.

Create a new java class called NetworkHelper with the following:

Before you can make HTTP request in your Android app, you first need to add the Network permission in AndroidManifest.xml:

Now back in SignUp.java, add the following properties:

Set the EditText components in the onCreate method:

Implement the signup method to send a POST request to :8000/signup with the name an password provided:

Run the app and enter a name and password. If the user account was successfully created you will get back a 201 Created status code and should see the newly created user on the Admin Dashboard:

Finally, let’s finish off with the Login screen. In activity_login.xml, add the following in RelativeLayout:

Add the properties to Login.java:

And do the same view binding operation in onCreate:

Implement the login method:

Run the app and login with the user name and password that you previously chose. If the authentication was successfull, you will get back a 200 OK status code:

NOTE: All of the Couchbase Lite SDKs have a method on the Replication object that takes a name and password and performs the authentication for you so you will likely not have to make that POST request to /smarthome/_session.


In this tutorial, you learnt how to use the Admin REST API to create users through a Sign Up screen in an Android app.


Posted by James Nocentini, Technical Writer, Mobile, Couchbase

James Nocentini is the Technical Writer in charge of the documentation for Couchbase Mobile. Previously, he worked as a Developer Advocate and before that as a front-end developer for HouseTrip. He also enjoys writing Android tutorials for raywenderlich.com in his spare time.

One Comment

  1. Miguel Angel Diaz Lopez April 25, 2017 at 12:58 pm

    Incredible post! I have a doubt, How can I to connect Couchbase Sync Gateway to other repository like active directory, etc. or are there a way to obtain a Single Sign On between Sync Gateway and Couchbase Server?

Leave a reply