Skip to content

Sessions API Reference ​

GET /me/activity ​

List the current user's login activity

Use in account security settings to review this user's resolved password, passkey, MFA, and OIDC login attempts. The method values are password, passkey, mfa, and oidc respectively; step_up records MFA-only step-up verification (see POST /auth/step-up/begin and POST /auth/step-up/complete). Results contain only rows whose user_id matches the bearer subject and are ordered by descending numeric activity ID. The cursor is a non-negative decimal string ID (omit, leave empty, or use 0 for the newest page); IDs remain numeric in items. See REST pagination for the shared limit, envelope, and terminal-cursor contract.

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "at": "2026-01-02T12:00:00Z",
      "id": "42",
      "ip": "203.0.113.5",
      "method": "password",
      "result": "success",
      "user_agent": "ExampleBrowser/1.0",
      "user_id": "01J8Z3USER000000000000001"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400cursor must be a non-negative integerInvalid Request; Invalid Request
400limit must be a positive integerInvalid Request; Invalid Request
401authentication failedUnauthorized
500authentication service unavailableInternal Server Error

GET /me/sessions ​

List the current user's sessions

Lists active, unexpired refresh sessions belonging to the bearer user, ordered by created_at ascending and session ID ascending. Returned IDs are opaque token digests and each row contains created_at, last_active_at, and expires_at. The cursor is an opaque composite of the full ordering key. See REST pagination for the shared collection contract.

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-01-31T00:00:00Z",
      "id": "8d7e5b3a0f6f4e1d...",
      "last_active_at": "2026-01-02T12:00:00Z"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400cursor is not a valid session cursorInvalid Request; Invalid Request
400limit must be a positive integerInvalid Request; Invalid Request
401authentication failedUnauthorized
500authentication service unavailableInternal Server Error

DELETE /me/sessions/{id} ​

Revoke one own session

Use when a user signs out another browser or device. Foreign, expired, revoked, or unknown IDs all return the same 404 response.

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

DELETE /users/{id}/sessions ​

Revoke every session for a user

Use for incident response or after an administrative password reset. It revokes all refresh sessions for the target user and returns no body.

Required permission — iam:sessions:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /users/{id}/sessions ​

List a user's sessions

Lists active, unexpired refresh sessions for the path user, ordered by created_at ascending and session ID ascending. Rows include created_at, last_active_at, and expires_at; client metadata and refresh tokens are never returned. The cursor is an opaque composite of the full ordering key. See REST pagination for the shared collection contract.

Required permission — iam:sessions:any

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-01-31T00:00:00Z",
      "id": "8d7e5b3a0f6f4e1d...",
      "last_active_at": "2026-01-02T12:00:00Z"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400cursor is not a valid session cursorInvalid Request; Invalid Request
400limit must be a positive integerInvalid Request; Invalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

DELETE /users/{id}/sessions/{sid} ​

Revoke one user's session

Use to revoke one device session during security review. The session must belong to the path user; foreign IDs return not_found.

Required permission — iam:sessions:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.
sidPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /users/{id}/sessions/{sid} ​

Get a user's session metadata

Use to inspect one session owned by the path user. Unknown user/session pairs and sessions belonging to another user return the same generic not-found response. Retained revoked or expired sessions remain readable. The response contains only the session ID, timestamps, and optional revocation metadata; it never returns refresh tokens or client metadata.

Required permission — iam:sessions:any Requires iam:sessions:any; reads do not require step-up authentication.

Path parameters ​

ParameterDescription
idPath parameter.
sidPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "expires_at": "2026-01-31T00:00:00Z",
  "id": "8d7e5b3a0f6f4e1d...",
  "last_active_at": "2026-01-02T12:00:00Z",
  "revoke_reason": "logout",
  "revoked_at": "2026-01-03T09:00:00Z"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error