CouchDB doesn’t actually use API keys in the way you might expect; it relies on a more traditional cookie-based authentication mechanism that you can leverage with long-lived tokens.
Let’s see this in action. Imagine you want to interact with CouchDB from a script without embedding your password directly. First, you’ll need to obtain a session cookie.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "admin", "password": "your_password"}' \
http://localhost:5984/_session
This command hits the _session endpoint with your username and password. The response will look something like this:
{
"ok": true,
"name": "admin",
"roles": [
"_admin"
],
"info": {
"id": "org.couchdb.user:admin",
"userCtx": {
"name": "admin",
"roles": [
"_admin"
]
},
"authentication_handlers": [
"cookie",
"basic",
"jwt"
]
}
}
Crucially, your browser or curl will automatically store the Set-Cookie header from this response. This cookie is your ticket to authenticated access. For subsequent requests, you’ll include this cookie.
curl -X GET \
-b "AuthSession=your_session_cookie_value" \
http://localhost:5984/your_database/_all_docs
The -b flag tells curl to send the specified cookie. Now, to simulate an "API key," you can create a dedicated CouchDB user with limited privileges and use their credentials to generate a session cookie, which you can then store securely and use in your scripts. This user is your "API key."
This approach solves the problem of needing to expose your primary administrator credentials for programmatic access. By creating a specific user for your application, you can grant it only the necessary permissions (e.g., read/write access to specific databases) and revoke it easily if compromised. The session cookie acts as a temporary, albeit potentially long-lived, bearer token.
Internally, CouchDB uses a standard HTTP cookie mechanism. When you authenticate via _session, it generates a server-side session associated with your user and sends a Set-Cookie header. Subsequent requests with that cookie are validated against the active session on the server. The AuthSession cookie is the primary one for this purpose.
The real magic, and the part most people overlook, is how CouchDB handles cookie expiration and renewal. While the _session endpoint can return a cookie that is valid for a long time (often effectively indefinite if not explicitly managed), it’s good practice to treat these cookies as potentially ephemeral. You can re-authenticate periodically to get a fresh session cookie, or if you’re managing applications, implement logic to detect a 401 Unauthorized response and re-initiate the authentication flow. The roles field in the _session response is also dynamic; if a user’s roles change on the server, their future authenticated requests will reflect those new roles without needing a new session cookie.
The next step in securing your CouchDB interactions is understanding how to manage user roles and permissions granularly for these "API key" users.