How does users_db_public work? (CouchDB 3.5.1)

[realistschuckle]

Using CouchDB v3.5.1, I updated my configuration to include the following settings.

[chttpd_auth]
users_db_public = true

The way I read the documentation is that, since I don't set public_fields, an authenticated user should be able to access their user record in _users:

If [public_fields is] unset or not specified, authenticated users can only retrieve their own document.

But, I can't get it to work with either Basic or JWT authentication. I only get 401 Forbidden results. (EDITED from "Cookie" to "Basic".)

Is this a bug?

Full config

[chttpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91
users_db_public = true  # What does this do?

[chttpd]
authentication_handlers = {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}
server_header_versions = false
enable_cors = true

[cors]
credentials = true
origins = http://localhost:1234
headers = authorization, accept, content-type, origin, referer

[jwt_auth]
roles_claim_path = roles

[jwt_keys]
hmac:_default = ...

[uuids]
algorithm = uuid_v7 

[vendor]
name = ...
version = 1.0.0

[couch_peruser]
enable = true

[couchdb]
uuid = ...
single_node = true

[admins]
admin = ...

[rnewson]

I think perhaps you are just passing the wrong credentials? You can confirm it by trying to GET the /_session endpoint with basic auth. Below I show that a user can fetch their own document if they are authenticated, it works whether users_db_public is false (default) or true.

  ~ curl http://localhost:5984/_users/org.couchdb.user:rnewson -XPUT -d '{}'
{"error":"forbidden","reason":"doc.type must be user"}
➜  ~ curl http://localhost:5984/_users/org.couchdb.user:rnewson -XPUT -d '{"type":"user"}'
{"error":"forbidden","reason":"doc.name is required"}
➜  ~ curl http://localhost:5984/_users/org.couchdb.user:rnewson -XPUT -d '{"type":"user","name":"rnewson"}'
{"error":"forbidden","reason":"doc.roles must exist"}
➜  ~ curl http://localhost:5984/_users/org.couchdb.user:rnewson -XPUT -d '{"type":"user","name":"rnewson","roles":[],"password":"wibble"}'
{"ok":true,"id":"org.couchdb.user:rnewson","rev":"1-a71ab3df6d73329402c357eb8969b997"}
➜  ~ curl http://rnewson:wibble@localhost:5984/_users/org.couchdb.user:rnewson
{"_id":"org.couchdb.user:rnewson","_rev":"1-a71ab3df6d73329402c357eb8969b997","password_scheme":"pbkdf2","pbkdf2_prf":"sha256","salt":"0472b43b8ceff9e0712bd552a4593de4","iterations":600000,"derived_key":"6392866e5afe7b4cdb446cac97605b76a1a6b023c0a2e013fd6cafc959cdb310","type":"user","name":"rnewson","roles":[]}
➜  ~ curl http://localhost:5984/_session -d 'name=rnewson&password=wibble' -i
HTTP/1.1 200 OK
cache-control: must-revalidate
content-length: 40
content-type: application/json
date: Thu, 02 Apr 2026 09:13:48 GMT
server: CouchDB/3.5.1-3083d28-dirty (Erlang OTP/26)
set-cookie: AuthSession=cm5ld3Nvbjo2OUNFMzM0RDpl0c7UczY5vlswc0zpUKi3q1mvuBdihhFOkHc7VwpOng; Version=1; Expires=Thu, 02-Apr-2026 09:23:49 GMT; Max-Age=600; Path=/; HttpOnly

{"ok":true,"name":"rnewson","roles":[]}
➜  ~ curl http://localhost:5984/_users/org.couchdb.user:rnewson -H 'cookie: AuthSession=cm5ld3Nvbjo2OUNFMzM0RDpl0c7UczY5vlswc0zpUKi3q1mvuBdihhFOkHc7VwpOng'
{"_id":"org.couchdb.user:rnewson","_rev":"1-a71ab3df6d73329402c357eb8969b997","password_scheme":"pbkdf2","pbkdf2_prf":"sha256","salt":"0472b43b8ceff9e0712bd552a4593de4","iterations":600000,"derived_key":"6392866e5afe7b4cdb446cac97605b76a1a6b023c0a2e013fd6cafc959cdb310","type":"user","name":"rnewson","roles":[]}

[realistschuckle]

Hi, @rnewson! Thank you for your reply and your examples. Unfortunately, I can't reproduce what you have. Here's what I get.

Unexpected behavior

Using the example.com/person@mailhost.com user with Basic Auth to access their user record, I get a 403 Forbidden.

curl --user 'example.com/person@mailhost.com:password' \
    'http://localhost:5984/_users/org.couchdb.user%3Aexample.com%2Fperson%40mailhost.com'

{"error":"forbidden","reason":"You are not allowed to access this db."}

Using a JWT with the sub claim set to example.com/person@mailhost.com to access their user record, I get a 403 Forbidden.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlLmNvbS9wZXJzb25AbWFpbGhvc3QuY29tIiwiZXhwIjoxNTE2MjM5MDIyMCwicm9sZXMiOltdfQ.fro4XKGs9JrABBWkvXAtGHnuniwlxYeGGH_YW3OKWwk' \
    http://localhost:5984/_users/org.couchdb.user%3Aexample.com%2Fperson%40mailhost.com

{"error":"forbidden","reason":"You are not allowed to access this db."}

Expected behavior

Using the admin user and Basic Auth, I get a successful response.

curl --user "admin:password" http://localhost:5984/_users/org.couchdb.user%3Aexample.com%2Fperson%40mailhost.com

{"_id":"org.couchdb.user:example.com/person@mailhost.com","_rev":"2-0d3c1123adaf781b754cc34c316b9f58","password_scheme":"pbkdf2","pbkdf2_prf":"sha256","salt":"bc00d465df6bf7c80248cc470116ebdd","iterations":600000,"derived_key":"dc6f67846acbfe4006406e27a9918b77f700ade03918fb4fbbec7f9a1921d1c2","name":"example.com/person@mailhost.com","roles":[],"type":"user"}

Using a user with a JWT and the _admin role, I get a successful response.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTUxNjIzOTAyMjAsInJvbGVzIjpbIl9hZG1pbiJdfQ.MPNmweY1wwOdNwAjW8CTnaNYHs3yC_xRlNGT8vx_3Oo"  \
    http://localhost:5984/_users/org.couchdb.user%3Aexample.com%2Fperson%40mailhost.com

{"_id":"org.couchdb.user:example.com/person@mailhost.com","_rev":"2-0d3c1123adaf781b754cc34c316b9f58","password_scheme":"pbkdf2","pbkdf2_prf":"sha256","salt":"bc00d465df6bf7c80248cc470116ebdd","iterations":600000,"derived_key":"dc6f67846acbfe4006406e27a9918b77f700ade03918fb4fbbec7f9a1921d1c2","name":"example.com/person@mailhost.com","roles":[],"type":"user"}

Using the example.com/person@mailhost.com user with Basic Auth and an incorrect password to access their user record, I get a 401 Unauthorized response.

curl --user 'example.com/person@mailhost.com:not-my-password' \
    'http://localhost:5984/_users/org.couchdb.user%3Aexample.com%2Fperson%40mailhost.com'

{"error":"unauthorized","reason":"Name or password is incorrect."}

Using the example.com/person@mailhost.com user with Basic Auth to access their user-specific database, I get a successful response.

curl --user 'example.com/person@mailhost.com:password' \
    http://localhost:5984/userdb-6578616d706c652e636f6d2f706572736f6e406d61696c686f73742e636f6d/_all_docs

{"total_rows":0,"offset":0,"rows":[]}

Using a JWT with the sub claim set to example.com/person@mailhost.com to access their user-specific database, I get a successful response.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlLmNvbS9wZXJzb25AbWFpbGhvc3QuY29tIiwiZXhwIjoxNTE2MjM5MDIyMCwicm9sZXMiOltdfQ.fro4XKGs9JrABBWkvXAtGHnuniwlxYeGGH_YW3OKWwk' \
    http://localhost:5984/userdb-6578616d706c652e636f6d2f706572736f6e406d61696c686f73742e636f6d/_all_docs

{"total_rows":0,"offset":0,"rows":[]}

Extra info

My _users security object

curl --user "admin:password" http://localhost:5984/_users/_security | jq

{
  "members": {
    "roles": [
      "_admin"
    ]
  },
  "admins": {
    "roles": [
      "_admin"
    ]
  }
}

My server config object

The server is running locally in a docker container.

{
  "uuids": {
    "algorithm": "uuid_v7"
  },
  "cors": {
    "credentials": "true",
    "headers": "authorization, accept, content-type, origin, referer",
    "origins": "http://localhost:1234"
  },
  "chttpd": {
    "authentication_handlers": "{chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}",
    "bind_address": "any",
    "enable_cors": "true",
    "port": "5984",
    "server_header_versions": "false"
  },
  "admins": {
    "admin": "PASSWORD-HASH"
  },
  "vendor": {
    "name": "Escribo Application Server",
    "version": "1.0.0"
  },
  "nouveau": {
    "url": "http://127.0.0.1:5987"
  },
  "jwt_keys": {
    "hmac:_default": "BASE64-ENCODED-SECRET"
  },
  "feature_flags": {
    "partitioned||*": "true"
  },
  "chttpd_auth": {
    "hash_algorithms": "sha256, sha",
    "secret": "SECRET",
    "users_db_public": "true"
  },
  "indexers": {
    "couch_mrview": "true"
  },
  "couch_peruser": {
    "enable": "true"
  },
  "prometheus": {
    "additional_port": "false",
    "bind_address": "127.0.0.1",
    "port": "17986"
  },
  "httpd": {
    "bind_address": "127.0.0.1",
    "port": "5986"
  },
  "smoosh": {
    "state_dir": "./data"
  },
  "jwt_auth": {
    "roles_claim_path": "roles"
  },
  "couch_httpd_auth": {
    "authentication_db": "_users"
  },
  "couchdb_engines": {
    "couch": "couch_bt_engine"
  },
  "couchdb": {
    "database_dir": "./data",
    "single_node": "true",
    "uuid": "UUID",
    "view_index_dir": "./data"
  }
}