Get Session

Retrieves detailed information about a specific session, including the current status of all IP rules. Use this endpoint to poll for status updates after starting a session or to inspect session details.

Request

GET /sessions/{id}

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the session

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>

Response

Returns a SessionResponse object with complete session details and current IP rule status.

{
  "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
    },
    {
      "id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
      "resourceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "resourceName": "Staging API SG",
      "ipVersion": 4,
      "ipAddress": "203.0.113.42",
      "status": "APPLIED",
      "providerRuleId": "sgr-abcdef0123456789f",
      "appliedAt": "2026-02-18T10:30:18Z",
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Response Fields

All fields are identical to the Start Session endpoint response.

Error Responses

Status Code	Error	Description
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Session belongs to different user (or API key lacks sessions:read)
404	Not Found	Session does not exist

Example

Request with JWT

curl https://api.entryguard.io/api/v1/sessions/3fa85f64-5717-4362-b98f-9ddd36e4b010 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Request with API Key

curl https://api.entryguard.io/api/v1/sessions/3fa85f64-5717-4362-b98f-9ddd36e4b010 \
  -H "X-API-Key: eg_live_1234567890abcdef"

Response - Active Session

{
  "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"
}

Response - Partial Session (with failure)

{
  "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": "PARTIAL",
  "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
    },
    {
      "id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
      "resourceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "resourceName": "Invalid SG",
      "ipVersion": 4,
      "ipAddress": "203.0.113.42",
      "status": "FAILED",
      "providerRuleId": null,
      "appliedAt": null,
      "removedAt": null,
      "errorMessage": "Security group sg-invalid does not exist"
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Use Cases

• Poll for session status updates after POST /sessions returns PENDING
• Monitor progress of IP rule application
• Debug failed rule applications using errorMessage field
• Display detailed session information in UI
• Verify session is fully active before proceeding with work