Stop Session

Manually stops an active session and revokes all associated IP whitelist rules. The session transitions to EXPIRING status while rules are being removed asynchronously, then to CANCELLED once complete. Use this when the user is finished working and wants to revoke access immediately instead of waiting for automatic expiration.

Request

POST /sessions/{id}/stop

Path Parameters

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

Authentication

Requires either:

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

Authorization: Bearer <access_token>

OR

X-API-Key: <api_key>

Request Body

No request body required.

Response

Returns a SessionResponse object with status transitioning to EXPIRING and endedReason set to MANUAL.

{
  "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": "EXPIRING",
  "startedAt": "2026-02-18T10:30:00Z",
  "expiresAt": "2026-02-18T12:30:00Z",
  "endedAt": "2026-02-18T11:15:30Z",
  "endedReason": "MANUAL",
  "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": "REMOVING",
      "providerRuleId": "sgr-0123456789abcdef0",
      "appliedAt": "2026-02-18T10:30:15Z",
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Response Fields

All fields are identical to the Start Session endpoint response, with these specific changes:

Field	Value
status	EXPIRING (transitions to CANCELLED once all rules removed)
endedAt	Current timestamp when stop was requested
endedReason	MANUAL (user-initiated stop)
resourceIps[].status	REMOVING (transitions to REMOVED once revoked)

Error Responses

Status Code	Error	Description
400	Bad Request	Session is not in a stoppable state (already expired/cancelled)
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Session belongs to different user (or API key lacks sessions:write)
404	Not Found	Session does not exist

Example

Request with JWT

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

Request with API Key

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

Response - Immediately After Stop

{
  "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": "EXPIRING",
  "startedAt": "2026-02-18T10:30:00Z",
  "expiresAt": "2026-02-18T12:30:00Z",
  "endedAt": "2026-02-18T11:15:30Z",
  "endedReason": "MANUAL",
  "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": "REMOVING",
      "providerRuleId": "sgr-0123456789abcdef0",
      "appliedAt": "2026-02-18T10:30:15Z",
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Response - After Cleanup Complete

Poll GET /sessions/{id} to see final state:

{
  "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": "CANCELLED",
  "startedAt": "2026-02-18T10:30:00Z",
  "expiresAt": "2026-02-18T12:30:00Z",
  "endedAt": "2026-02-18T11:15:30Z",
  "endedReason": "MANUAL",
  "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": "REMOVED",
      "providerRuleId": "sgr-0123456789abcdef0",
      "appliedAt": "2026-02-18T10:30:15Z",
      "removedAt": "2026-02-18T11:15:35Z",
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Status Transitions

ACTIVE → EXPIRING → CANCELLED
  ↑          ↓
  └─ (manual stop) ─┘

Reference Counting

IP rules are reference-counted. If multiple active sessions share the same IP address and resource, the rule will not be revoked until ALL sessions are stopped or expired. This prevents disruption when users have overlapping sessions.

Use Cases

• User finishes work and wants immediate access revocation
• Security concern requiring immediate session termination
• Switching to different IP address (stop current, start new)
• "Logout" functionality in client applications
• Cleanup before long period of inactivity