Session Management

Gate Identity gives you full control over the active sessions of your end-users. You can list all sessions for a given identity, revoke them all at once (force logout everywhere), or revoke a single session by ID.

Endpoints

Method	Path	Description
`GET`	`/v1/gate/identities/{id}/sessions`	List all active sessions for an identity
`DELETE`	`/v1/gate/identities/{id}/sessions`	Revoke all sessions for an identity
`DELETE`	`/v1/gate/sessions/{session_id}`	Revoke a single session

All endpoints require a tenant API key with the gate scope. Tenant isolation is enforced — you can only manage sessions of identities that belong to your tenant.

List Sessions

GET /v1/gate/identities/{id}/sessions

Returns all active sessions for the given identity. The response is the raw Kratos session array.

curl https://api.vernesoft.com/v1/gate/identities/f47ac10b-.../sessions \
  -H 'Authorization: Bearer vrn_9f8a7...'

Key fields per session:

Field	Description
`id`	Session ID — use this to revoke a specific session
`active`	Whether the session is currently valid
`authenticated_at`	When the session was created
`expires_at`	When the session will expire automatically
`authentication_methods`	Methods used (password, code, totp, etc.)
`devices`	IP address and user agent of the device

Revoke All Sessions

DELETE /v1/gate/identities/{id}/sessions

Immediately invalidates all active sessions for the identity. The user will be logged out on all devices on their next request.

Returns 204 No Content.

curl -X DELETE https://api.vernesoft.com/v1/gate/identities/f47ac10b-.../sessions \
  -H 'Authorization: Bearer vrn_9f8a7...'

Use cases:

User reports their account was compromised
You want a user's sessions ended for good, not just suspended — a deactivated user's sessions stop working at once but work again on reactivation
"Log out everywhere" button in your account settings

Revoke a Single Session

DELETE /v1/gate/sessions/{session_id}

Revokes one specific session by its ID — the id of an entry in the list above. Only the other sessions of the same person keep working.

Status	Meaning
`204`	The session is revoked. Revoking a session of your user that is already revoked is `204` too, so the call can be retried.
`404`	No such session — the ID does not exist, is not a UUID, or belongs to someone who is not one of your end users. These cases cannot be told apart, so the endpoint cannot be used to find out which session IDs exist.
`502`	Gate could not reach its identity service. Retry.

curl -X DELETE https://api.vernesoft.com/v1/gate/sessions/8e4f0b2a-... \
  -H 'Authorization: Bearer vrn_9f8a7...'

Use case: The user sees an unfamiliar device in their session list and clicks "Log out this device".

Typical Integration Pattern

// 1. Fetch the user's active sessions
const res = await fetch(`/v1/gate/identities/${userId}/sessions`, {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const sessions = await res.json()

// 2. Display to user — let them revoke suspicious ones
for (const session of sessions) {
  const { id, devices, authenticated_at } = session
  // render session row with a "Revoke" button
}

// 3. Revoke on user action
async function revokeSession(sessionId) {
  await fetch(`/v1/gate/sessions/${sessionId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${apiKey}` },
  })
}

// 4. Or revoke all at once (e.g., after a compromise)
async function revokeAllSessions(userId) {
  await fetch(`/v1/gate/identities/${userId}/sessions`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${apiKey}` },
  })
}

Notes

Sessions expire automatically based on the Kratos session lifetime configured for your tenant.
Revoking a session does not delete the identity — the user can log in again unless the identity is also deactivated (see Activate / Deactivate).
Deactivating an identity does not revoke its sessions: they stop working while it is inactive and work again once it is active. Revoke them as well if the user must sign in again after reactivation.
The devices array may be empty if Kratos could not detect device information for the session.