Session_API

The Session API manages sessions for CouchDB access.

Session information is stored on the client using a Cookie (named AuthSession).

Log in

To create a session (=log in), do a

  POST /_session

with "name" and "password" fields or a

  GET /_session

with (by default) a standard Basic Authorization header:

   Authorization: Basic <base64-encoded-username:password>

The username is the "name" field of a user's record in CouchDB's _users database.

There is an optional "next" parameter that can be used to force a redirection after CouchDB processed a successful login.

In case of success, the POST or GET /_session command will return a JSON value:

  {
    "ok": true,
    "userCtx": {
      "name": "username",
      "roles": ["role1","role2"]
    },
    "info": {
      "authentication_db":"_users",
      "authentication_handlers":["oauth","cookie","default"],
      "authenticated":"default"
    }
  }

Note how the userCtx field is similar to the user context (userCtx) parameter of some of the Javascript functions.

In case of error, the POST /_session command will return a JSON value:

  {
    "error":"Name or password is incorrect."
  }

Possible return values:

• 200 OK (with Cookie)
• 302 Redirection (with Cookie) -- if "next" parameter was provided
• 401 Unauthorized

Log out

To delete the session, do a

  DELETE /_session

which will remove the session cookie.

An optional parameter "next" can be provided to redirect the browser.

Possible return values:

• 200 OK (cookie removed)
• 302 Redirection (cookie removed) -- if "next" parameter was provided

Session information

To retrieve the current session's information, do a

  GET /_session

which will retrieve the session data (based on the session cookie).

If the session is valid the GET method will return the same structure as provided by the successful POST that started the session.

If the session is not valid (not logged in, etc.) an exception will be thrown with an "unauthorized" error.

Note: it seems Futon does not use POST but simply submits a GET /_session with the proper Authorization header.

Session Timeout

The session timeout is specified by the "timeout" parameter in the "couch_httpd_auth" section of configuration. If not specified it defaults to 600 seconds (10 minutes).