What is a CouchDB _security object and how do you configure roles and members?

The _security object is a special document stored at /db/_security. It defines which users and roles can act as admins (write design documents, change security) or members (read and write regular documents) for that specific database. Every database has one.

{
  "admins": {
    "names": ["alice", "bob"],
    "roles": ["db_admin_role"]
  },
  "members": {
    "names": ["charlie"],
    "roles": ["viewer", "editor"]
  }
}

# Set the _security object
curl -X PUT http://admin:pass@localhost:5984/mydb/_security \
  -H "Content-Type: application/json" \
  -d '{
    "admins":  { "names": ["alice"], "roles": ["db_admin_role"] },
    "members": { "names": [],        "roles": ["editor","viewer"] }
  }'

# Read the current _security object
curl http://admin:pass@localhost:5984/mydb/_security

Key behaviors:

• If the members list is empty (both names and roles), the database is readable by any authenticated user or even anonymously (public database).
• Server admins bypass the _security object entirely — they always have full access to every database.
• Roles are arbitrary strings. They are assigned to users in the _users database under the roles array in the user document. CouchDB does not provide a built-in role management UI; roles are managed by updating user documents.
• Only server admins and database admins can modify the _security object.