Admin Stop Session

Allows organization administrators to manually stop any user's session within their organization. This is useful for security incidents, policy enforcement, or when a user's session needs to be terminated remotely. The session transitions to EXPIRING status and IP rules are revoked asynchronously.

Request

POST /sessions/admin/{id}/stop

Path Parameters

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

Authentication

Requires a Bearer JWT token with ORG_ADMIN role.

Authorization: Bearer <access_token>

Request Body

No request body required.

Response

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

{
  "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:45:20Z",
  "endedReason": "ADMIN",
  "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 admin stop was requested
endedReason	ADMIN (admin-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 JWT token
403	Forbidden	User does not have ORG_ADMIN role
404	Not Found	Session does not exist or belongs to different organization

Example

Request

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

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:45:20Z",
  "endedReason": "ADMIN",
  "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

{
  "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:45:20Z",
  "endedReason": "ADMIN",
  "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:45:25Z",
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Differences from User Stop

Aspect	User Stop (POST /sessions/{id}/stop)	Admin Stop (POST /sessions/admin/{id}/stop)
Authorization	User can only stop their own sessions	Admin can stop any session in their org
Ended Reason	MANUAL	ADMIN
Audit Trail	User name in audit log	Admin name + affected user in audit log
Use Cases	User-initiated logout	Security enforcement, policy violations

Audit Trail

Admin stops are logged in the audit trail with:

• Event type: SESSION_STOPPED
• Actor: Admin user who performed the action
• Target: User whose session was stopped
• Details: Session ID, IP address, reason

Query audit logs:

curl https://api.entryguard.io/api/v1/audit-logs?eventType=SESSION_STOPPED \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Use Cases

• Security Incident Response: Immediately revoke access for compromised accounts
• Policy Enforcement: Terminate sessions that violate security policies
• Account Suspension: Stop all sessions when disabling a user account
• Emergency Access Revocation: Remove access during investigations
• Compliance: Enforce session time limits or access windows
• Remote Management: Help users who cannot stop their own sessions

Best Practices

1. Document the reason for admin stops in your internal systems
2. Notify affected users when their sessions are terminated
3. Review audit logs regularly for admin actions
4. Consider bulk operations when stopping multiple sessions
5. Coordinate with security teams before stopping sessions during incidents

Related Endpoints

• GET /sessions/admin - List all organization sessions
• POST /sessions/{id}/stop - User self-service stop
• GET /audit-logs - View audit trail of admin actions