Pragmatism in the real world

Use curl to create a CouchDB admin user

This too me longer to find than it should have done, so I’m writing it here for future me.

When you install CouchDB, it is in a mode where anyone can do anything with the database including creating and deleting databases. This is called “Admin Party” mode which is a pretty cool name, but not what I want.

Creating admin users

To create a user in 1.6 (I’ve not used 2.0 yet, but assuming it’s the same) you simply click on the “Fix This” link in Futon which is available at http://localhost:5984/_utils/ by default.

As CouchDB’s entire API is essentially a RESTFul API, to do this via the command line, you simply PUT a new user to into the _configs/admins collection like this:

CouchDB 1.x:

curl -s -X PUT http://localhost:5984/_config/admins/rob -d '"123456"'

CouchDB 2.x:

curl -s -X PUT http://localhost:5984/_node/couchdb@localhost/_config/admins/rob -d '"123456"'

This creates an admin user called rob with a password of 123456. Note that the password within the body of the PUT request must be a quoted string. This caught me out for a while!

From this point on, we can then use basic authentication to do admin-y things, such as create a bookshelf_api database:

$ curl -s -X PUT http://rob:123456@localhost:5984/bookshelf_api

Other users

You can also set up per-database users which is handy for limiting what your application can do when connected to CouchDB. This is done creating users in the /_users/ collection and then assigning them to a class in the _security collection of the database. There are two default classes: “members” and “admins” where members can modify data, but not design documents and admins can modify all documents including user roles on that database.

10 thoughts on “Use curl to create a CouchDB admin user

  1. @spidey the API changed, and now you have to inform the node name in the URL, like this:
    curl -X PUT $HOST/_node/$NODENAME/_config/admins/root -d '"super_secret"'

    The default node is "nonode@nohost", so that would end up like:
    curl -X PUT $HOST/_node/nonode@nohost/_config/admins/root -d '"super_secret"'

    If you are unsure of what nodes you have, you can get info about all of them like this:
    curl -X GET $HOST/_membership

    And if you have already created an admin account you'll have to use it to be able to query (you'll be asked for the password):
    curl -X GET $HOST/_membership --user root

    1. @AlexandreNicastro Would you happen to know what my be causing the error message:
      `{"error":"nodedown","reason":"nonode@nohost is down"}`
      when I run
      `curl -X PUT $HOST/_node/nonode@nohost/_config/admins/root -d '"super_secret"'`?

  2. You are using the wrong information for the default node. Try the following:

    curl -X PUT $HOST/_node/couchdb@localhost/_config/admins/root -d '"super_secret"'

  3. I am very new on couchdb, I have installed couchdb(2.3.1) and after setting up, some DB's, user role etc.
    Now I wanted to set dbadmin, So for this I am hitting this command > curl -X PUT $HOST/_node/$NODENAME/_config/admins/anna -d '"secret"
    " from cmd. It saying output "curl: (6) Could not resolve host: $HOST".

    Can someone please save me from here.

    1. Try replacing $HOST with the correct hostname for your CouchDB and $NODENAME for the correct name of the database within it.

  4. Hi! I use CouchDB Fauxton for several days. Where exactly I can write the curl command?

    Тhanks in advance!

Comments are closed.