A newer version of this documentation is available.

View Latest

Couchbase Passwords

    Couchbase Server requires that administrators and applications authenticate, in order to gain access to data, settings, and statistics. Authentication requires that a unique password be provided.

    Who Requires a Password?

    Every user of Couchbase Server requires a password. A user may be either an administrator or an application. An application may be a program or server, or may be a simple, single command-line query.

    The Full Administrator, who installs and configures Couchbase Server (and so has full read-write access to the whole system), defines their own username and password during the configuration-process: see Initialize the Cluster, for details. Subsequently, this administrator can add additional administrators to the system; assigning a username and password to each. Whenever any needs to log into the Couchbase Web Console in order to inspect data, statistics, and settings (and possibly make changes), they must specify their own unique username-password combination, at the authentication-prompt provided by the server.

    An application must pass both a username and a password as parameters. Therefore, Couchbase CLI commands, N1QL queries, and executables supported by the Couchbase SDK all provide syntax to allow the passing of a username and password.

    Additionally, a special master password may be designed and used by the Full Administrator, in order to manage server-secrets. See Secret-Management, for details.

    What Password-Strength is Required?

    Couchbase Server provides a default password-policy. This demands only that the password have a minimum of six characters.

    For pre-production purposes, it may be desirable to strengthen this default password-policy. For production purposes, it should be considered essential to do so. The password-policy can be set by the Full Administrator, by means of the Couchbase CLI command setting-password-policy. This allows you to specify that every Couchbase Server-password should:

    • Contain a minimum-number of characters; which can be any number between 0 and 100.

    • Contain at least one uppercase character.

    • Contain at least one lowercase character.

    • Contain at least one special character.

    • Contain at least one digit.

    It is recommended that for production-purposes, a password should have at least eight characters, including characters from three of the following five groups: lowercase letters; uppercase letters; numbers; symbols; unicode characters.

    Passwords should be rotated on a regular basis.

    You can reset any forgotten administrative passwords using the Couchbase CLI command reset-admin-password.

    We strongly suggest that you use strong user passwords, and if you want to enforce a strong password, you should use a strong password policy. Password enforcement is done during password setting and rotation.


    Couchbase Server can be accessed by administrators on a secure connection, protected by SSL/TLS. Additionally, the passing of authentication-credentials is protected at all times by means of the SASL framework. See Password-Based Authentication, for details.

    Usernames and Roles

    To authenticate, every Couchbase Server-user must specify a username as well as a password. The restrictions on username-design are that each should be unique to the cluster; and that none of the following characters be used: ( ) < > @ , ; : \ " / [ ] ? = { }. Usernames may not be more than 128 UTF-8 characters in length; and it is recommended that they be no more than 64 UTF-8 characters in length, in order to ensure successful onscreen display.

    Each user is associated with one or more roles, which permit limited access-privileges. Therefore, once a user has authenticated, their role-assignment is examined, and an appropriate degree of access is granted to them by Couchbase Server. See Authorization, for details.

    Note that usernames and role-names are case sensitive.