How does CouchDB implement authentication — cookie auth, JWT, and proxy auth?

CouchDB supports four authentication mechanisms, configurable simultaneously. Each request is checked against the enabled handlers in order.

1. Basic Authentication — HTTP Basic Auth over HTTPS. Credentials are sent with every request. Simple to implement but requires HTTPS in production to avoid credential exposure.

curl -u admin:password http://localhost:5984/_session

2. Cookie (Session) Authentication — the most common for web apps. POST credentials to /_session to receive a session cookie, then use that cookie for subsequent requests. The cookie has a configurable timeout.

# Login and get a session cookie
curl -X POST http://localhost:5984/_session \
  -H "Content-Type: application/json" \
  -d '{"name":"alice","password":"s3cret"}'
# Set-Cookie: AuthSession=abc123...; Version=1; Secure; HttpOnly

# Use the session
curl -b "AuthSession=abc123..." http://localhost:5984/mydb/_all_docs

# Logout
curl -X DELETE http://localhost:5984/_session -b "AuthSession=abc123..."

3. JWT Authentication (CouchDB 3.3+) — validates a JSON Web Token in the Authorization: Bearer {token} header. The JWT must contain a sub claim (the username) and optionally _couchdb.roles. CouchDB verifies the signature using a configured HMAC secret or RSA public key — it does not issue JWTs, only validates them.

[jwt_auth]
required_claims = exp
[jwt_keys]
hmac:default = aGVsbG93b3JsZA==

4. Proxy Authentication — for reverse-proxy setups (nginx, HAProxy). The proxy authenticates the user externally and forwards the identity in headers (X-Auth-CouchDB-UserName, X-Auth-CouchDB-Roles, X-Auth-CouchDB-Token). CouchDB trusts the headers if the correct HMAC token is present.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.