> Markdown version of https://authpi.com/docs/reference/core-api/sessions/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Sessions — AuthPI Core API

User session management endpoints. Sessions track authenticated users and their tokens. Use these endpoints to monitor, suspend, or revoke user sessions.

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/users/{user_id}/sessions

**List User Sessions**

Lists all sessions for a user.

Sessions represent authenticated contexts for a user. Each session tracks:
- **Status** - Current state (active, suspended, revoked, expired)
- **Device info** - User agent, IP address, device fingerprint
- **Tokens** - Associated access and refresh tokens
- **Activity** - Last activity timestamp

**Session statuses:**
- **inactive** - Session created but not yet activated (pre-token issuance)
- **active** - Normal operational state
- **suspended** - Temporarily blocked by admin (can be reactivated)
- **revoked** - Permanently terminated (logout or security action)
- **expired** - Session lifetime exceeded

Use this endpoint to:
- Show users their active sessions
- Identify suspicious sessions for security review
- Audit session history

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `user_id` | string | Required | The unique identifier of the user |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | inactive \| active \| expired \| revoked \| suspended | Optional | Filter sessions by status |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Sessions retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/sessions/{session_id}

**Get Session**

Retrieves detailed information about a specific session.

Returns complete session data including:
- **User info** - The user ID associated with this session
- **Client info** - The OAuth client that initiated the session
- **Device context** - User agent, IP address, device fingerprint
- **Timestamps** - Created, last activity, expiration times
- **Token metadata** - Current access/refresh token JTIs (not the tokens themselves)

Use this endpoint to:
- Investigate suspicious activity
- Verify session validity before sensitive operations
- Get context for security audit logs

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `session_id` | string | Required | The unique identifier of the session |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Session retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/sessions/{session_id}/revoke

**Revoke Session**

Permanently revokes a session.

Revoking a session immediately:
- Invalidates all tokens associated with the session
- Prevents any further token refresh attempts
- Logs the user out of this session
- Revokes linked RP/client sessions when the target is an OP/SSO session
- Emits `session.terminated` events and OIDC backchannel logout per affected client session

**Revocation reasons:**
Include a `reason` in the request body for audit purposes — one of:
`user_logout`, `admin_action`, `security_event`, `password_changed`, `inactivity`, `token_compromised`, `other`.

Pass `revoke_all_user_sessions: true` to revoke every non-terminal session belonging to this session's user ("log out everywhere"), including active, suspended, and not-yet-activated inactive sessions.

**Important:** This action is permanent. To temporarily block a session while investigating, use Suspend Session instead.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `session_id` | string | Required | The unique identifier of the session |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | user_logout \| admin_action \| security_event \| password_changed \| inactivity \| token_compromised \| … | Required |  |
| `reason_details` | string | Optional |  |
| `revoke_all_user_sessions` | boolean | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Session revoked successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/sessions/{session_id}/suspend

**Suspend Session**

Temporarily suspends a session.

Use suspension when you need to block access while investigating suspicious activity, without permanently revoking the session.

**When suspended:**
- All tokens immediately become invalid
- Token refresh attempts fail
- The session can be reactivated later

**Use cases:**
- Detected unusual activity requiring investigation
- User reports possible account compromise
- Temporary administrative hold

**Difference from revoke:**
- Suspended sessions can be reactivated
- Revoked sessions are permanently terminated

Include a `reason` in the request body for audit purposes.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `session_id` | string | Required | The unique identifier of the session |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | security_event \| token_compromised \| device_mismatch \| risk_review \| other | Required |  |
| `reason_details` | string | Optional |  |
| `suspend_all_user_sessions` | boolean | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Session suspended successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/sessions/{session_id}/reactivate

**Reactivate Session**

Reactivates a previously suspended session.

After investigation confirms the session is legitimate, use this endpoint to restore access.

**When reactivated:**
- Session status returns to `active`
- Tokens become valid again (if not expired)
- User regains access without re-authenticating

**Limitations:**
- Only suspended sessions can be reactivated
- Revoked or expired sessions cannot be reactivated
- The user must obtain new tokens via refresh if their previous tokens expired during suspension

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `session_id` | string | Required | The unique identifier of the session |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Session reactivated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |