Sessions

Token rotation and session management for the caller. Session management needs the session cookie; POST /auth/refresh needs the refresh cookie instead, and GET /auth/csrf-token is public. Sessions serialize camelCase; token hashes are never included:

Send X-GoAuth-Session: admin consistently for the admin frontend, including bootstrap, reads, refresh, and logout. Omit it for the ordinary app. The API selects separate cookies and CSRF tokens, with no fallback between contexts. Refresh and logout leave the other context's current credential unchanged. Session listing and explicit session revocation still operate on the caller's account, including its sessions in either context.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0 ...",
  "isRevoked": false,
  "expiresAt": "2025-01-31T12:00:00Z",
  "refreshExpiresAt": "2025-01-31T12:00:00Z",
  "createdAt": "2025-01-01T00:00:00Z",
  "lastActiveAt": "2025-01-01T12:00:00Z",
  "activeOrgId": "550e8400-e29b-41d4-a716-446655440000",
  "activeOrgRole": "member"
}

Email-verification policy also applies to existing sessions: protected routes return email_not_verified until the account verifies. Refreshing credentials does not remove that restriction or mark the account verified. The retained session can still finish verification and log out.

Refresh token

POST /auth/refresh

Rotates both tokens using the refresh cookie and sets the new cookies only while the session is within its idle timeout and optional maximum lifetime. No body: the refresh token is read from the cookie, not the JSON. A service-level refresh failure clears both cookies; a missing or empty refresh cookie returns 401 invalid_refresh without clearing cookies. Auth: refresh cookie.

Response 200 OK:

{ "step": "authenticated", "session": { "...": "the rotated session" } }

If email verification is required and the session owner is unverified, the rotated cookies are still returned, but the body is restricted:

{ "step": "verify_email", "email": "alice@example.com" }

It does not include a session object. Show the verification screen instead of rendering protected content. Refresh retains the session for verification; protected routes continue to enforce the current policy.

Errors: invalid_refresh (no refresh cookie was sent).

List sessions

GET /auth/sessions

Lists the caller's sessions, newest activity first, with the current one identified. Auth: Session.

Query:

Response 200 OK:

{
  "sessions": [{ "...": "session objects" }],
  "total": 5,
  "limit": 20,
  "offset": 0,
  "currentSessionId": "550e8400-..."
}

List all sessions

GET /auth/sessions/all

Same sessions without pagination. Auth: Session.

Response 200 OK:

{
  "sessions": [{ "...": "session objects" }],
  "currentSessionId": "550e8400-..."
}

Revoke one session

DELETE /auth/sessions/{id}

Terminates a specific session. Auth: Session.

Response 200 OK:

{ "message": "Session revoked" }

Errors: session_not_found.

Revoke many sessions

POST /auth/sessions/revoke

Revokes several of the caller's sessions at once (1 to 100). Auth: Session.

Request body:

{ "sessionIds": ["id1", "id2"] }

Response 200 OK:

{ "revoked": 2 }

Errors: invalid_input (empty list, or more than 100 IDs).

Revoke all sessions

DELETE /auth/sessions

Revokes every session except the current one. Auth: Session.

Response 200 OK:

{ "message": "Sessions revoked" }

Get CSRF token

GET /auth/csrf-token

Initializes or reads the browser/session-bound double-submit token. Auth: Public; send credentials so the server can bind to the current session or establish an anonymous browser binding.

Response 200 OK, always:

{ "token": "opaque-csrf-token" }

The response has Cache-Control: no-store. _csrf is HttpOnly, host-only at /; use the JSON value, not document.cookie. Echo it in X-CSRF-Token on unsafe requests. Login/logout and credential changes return replacement tokens in the same response header. Ordinary bootstrap requests reuse a valid token. CORS exposes X-CSRF-Token and Retry-After to allowed origins.

Next

• OAuth: login, callback, link, unlink
• Organizations: orgs, members, invites, active org