Sessions and cookies

Session token

After register or login, the client receives session.token — an opaque string stored in the sessions table. The API checks it with get_session_by_token; expired or deleted sessions yield 401.

Benefits over stateless JWT-only login:

• Revocation — delete the row (logout, compromised token).
• Device lists — GET /auth/sessions (non-expired sessions for the current user).
• Per-session logout — DELETE /auth/sessions/{session_id}.

Bearer transport (default)

cookie_transport=False (default)

• Clients send Authorization: Bearer <session.token>.
• set_token on the response is a no-op for Bearer (token is only in JSON).

Cookie transport

cookie_transport=True

• Register / login responses include Set-Cookie (name from cookie_name, default aura_token).
• Depends(auth.current_user()) reads the token via request.cookies.

Local HTTP

Browsers do not send cookies with the Secure attribute over plain http://. For local development set:

AuraAuth(
    database_url="...",
    secret="...",
    cookie_transport=True,
    cookie_secure=False,
)

Use cookie_secure=True (default) behind HTTPS in production.

Logout

POST /auth/logout revokes the current session (by token from header or cookie) and clears the cookie when cookie transport is enabled.