Appearance
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
| Status | Code | Detail |
|---|---|---|
| 400 | cursor must be a non-negative integer | Invalid Request; Invalid Request |
| 400 | limit must be a positive integer | Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal 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
| Status | Code | Detail |
|---|---|---|
| 400 | cursor is not a valid session cursor | Invalid Request; Invalid Request |
| 400 | limit must be a positive integer | Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path 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
| Status | Code | Detail |
|---|---|---|
| 400 | cursor is not a valid session cursor | Invalid Request; Invalid Request |
| 400 | limit must be a positive integer | Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
| sid | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
| sid | Path 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
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |