List Sessions

Retrieves all sessions for the authenticated user, including active, expired, and cancelled sessions. Sessions are ordered by creation date (most recent first).

Request

GET /sessions

Authentication

Requires either:

• Bearer JWT token with USER role, OR
• API Key with sessions:read permission

Authorization: Bearer <access_token>

OR

X-API-Key: <api_key>

Query Parameters

No query parameters are accepted. This endpoint always returns all sessions for the authenticated user.

Response

Returns an array of SessionResponse objects.

[
  {
    "id": "3fa85f64-5717-4362-b98f-9ddd36e4b010",
    "userId": "7c8b3f21-4d92-4a8e-9f3a-1e6c5b9d0a2b",
    "userName": "John Doe",
    "userEmail": "[email protected]",
    "ipv4Address": "203.0.113.42",
    "ipv6Address": null,
    "status": "ACTIVE",
    "startedAt": "2026-02-18T10:30:00Z",
    "expiresAt": "2026-02-18T12:30:00Z",
    "endedAt": null,
    "endedReason": null,
    "resourceIps": [
      {
        "id": "8e9f2a3b-1c4d-5e6f-7a8b-9c0d1e2f3a4b",
        "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "resourceName": "Production Database SG",
        "ipVersion": 4,
        "ipAddress": "203.0.113.42",
        "status": "APPLIED",
        "providerRuleId": "sgr-0123456789abcdef0",
        "appliedAt": "2026-02-18T10:30:15Z",
        "removedAt": null,
        "errorMessage": null
      }
    ],
    "createdAt": "2026-02-18T10:30:00Z"
  },
  {
    "id": "2eb74c53-4606-3251-a87e-8ccc25d3a00f",
    "userId": "7c8b3f21-4d92-4a8e-9f3a-1e6c5b9d0a2b",
    "userName": "John Doe",
    "userEmail": "[email protected]",
    "ipv4Address": "198.51.100.15",
    "ipv6Address": null,
    "status": "EXPIRED",
    "startedAt": "2026-02-17T14:00:00Z",
    "expiresAt": "2026-02-17T16:00:00Z",
    "endedAt": "2026-02-17T16:00:05Z",
    "endedReason": "EXPIRED",
    "resourceIps": [
      {
        "id": "7d8e1f2a-0b3c-4d5e-6f7a-8b9c0d1e2f3a",
        "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "resourceName": "Production Database SG",
        "ipVersion": 4,
        "ipAddress": "198.51.100.15",
        "status": "REMOVED",
        "providerRuleId": "sgr-fedcba9876543210f",
        "appliedAt": "2026-02-17T14:00:10Z",
        "removedAt": "2026-02-17T16:00:05Z",
        "errorMessage": null
      }
    ],
    "createdAt": "2026-02-17T14:00:00Z"
  }
]

Response Fields

Each session object contains the same fields as described in the Start Session endpoint.

Error Responses

Status Code	Error	Description
401	Unauthorized	Invalid or missing authentication
403	Forbidden	API key lacks sessions:read permission

Example

Request with JWT

curl https://api.entryguard.io/api/v1/sessions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Request with API Key

curl https://api.entryguard.io/api/v1/sessions \
  -H "X-API-Key: eg_live_1234567890abcdef"

Response

[
  {
    "id": "3fa85f64-5717-4362-b98f-9ddd36e4b010",
    "userId": "7c8b3f21-4d92-4a8e-9f3a-1e6c5b9d0a2b",
    "userName": "John Doe",
    "userEmail": "[email protected]",
    "ipv4Address": "203.0.113.42",
    "ipv6Address": null,
    "status": "ACTIVE",
    "startedAt": "2026-02-18T10:30:00Z",
    "expiresAt": "2026-02-18T12:30:00Z",
    "endedAt": null,
    "endedReason": null,
    "resourceIps": [
      {
        "id": "8e9f2a3b-1c4d-5e6f-7a8b-9c0d1e2f3a4b",
        "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "resourceName": "Production Database SG",
        "ipVersion": 4,
        "ipAddress": "203.0.113.42",
        "status": "APPLIED",
        "providerRuleId": "sgr-0123456789abcdef0",
        "appliedAt": "2026-02-18T10:30:15Z",
        "removedAt": null,
        "errorMessage": null
      }
    ],
    "createdAt": "2026-02-18T10:30:00Z"
  }
]

Session Status Values

Status	Description
PENDING	Session created, IP rules being applied
ACTIVE	All IP rules successfully applied
PARTIAL	Some IP rules applied, others failed
FAILED	All IP rules failed to apply
EXPIRING	Session is being cleaned up
EXPIRED	Session ended due to expiration
CANCELLED	Session manually stopped by user or admin

Use Cases

• Display session history in user dashboard
• Monitor active sessions
• Audit past access patterns
• Programmatically check if user has active session before starting new one