> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> API reference for Essal Access session management — list active sessions, revoke, and check MFA status.

## List Active Sessions

`GET /v1/access/users/{user_id}/sessions`

Returns all active sessions for a user.

```json theme={null}
{
  "data": [
    {
      "id": "sess_01HXYZSESS1",
      "created_at": "2026-07-10T08:30:00Z",
      "last_active_at": "2026-07-10T15:20:00Z",
      "ip_address": "203.0.113.10",
      "user_agent": "Chrome/126 on macOS",
      "mfa_verified": true
    }
  ]
}
```

***

## Revoke a Session

`DELETE /v1/access/sessions/{session_id}`

Immediately invalidates the session token. The user will be required to log in again.

**Response** — `204 No Content`

***

## Revoke All Sessions for a User

`POST /v1/access/users/{user_id}/sessions/revoke-all`

Logs the user out of all active sessions across all devices. Useful when a credential compromise is suspected.

**Response** — `200 OK`

```json theme={null}
{ "revoked_count": 3 }
```

***

## Check MFA Status

`GET /v1/access/users/{user_id}/mfa`

```json theme={null}
{
  "user_id": "usr_01HXYZ1234",
  "mfa_enabled": true,
  "methods": ["totp", "webauthn"],
  "last_verified_at": "2026-07-10T08:30:00Z"
}
```

***

## Enforce MFA for a Workspace

Require MFA for all users at the workspace level:

`PATCH /v1/access/settings`

```json theme={null}
{ "mfa_required": true, "mfa_grace_period_hours": 48 }
```

Users who have not enrolled MFA will be prompted on their next login and must enrol within the grace period before losing access.

<Warning>
  Enforcing MFA with a short grace period may lock out users who do not act quickly. Communicate the change to your team before enabling.
</Warning>