Session Management

Gate 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 an identity's sessions, revoked ones included (`active: false`)
`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 the sessions of the given identity as the raw Kratos session array. It is not only the live ones: a session you or the user revoked stays in the list with "active": false. Filter on active before you show the list to the user or count their devices.

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.

Status	Meaning
`204`	The user's sessions are revoked. Also `204` when the user has no sessions — never signed in, signed out already, or you revoked them a moment ago — so the call is safe to repeat and a "log out everywhere" button needs no special case.
`403`	`forbidden` — the identity is not one of your end users. This is also the answer for an id that does not exist, and for a user you deleted through the API: once deleted, the id is indistinguishable from another account's user, so it cannot be used to find out which ids exist.
`404`	`not_found` — Gate still counts the user as yours, but the identity service no longer has them. This happens only when the user was removed some way other than the API (for example directly in the identity service), or in the instant between the check and the revocation. Do not wait for it after a delete you made yourself.
`502`	`upstream_unavailable` — Gate could not reach its identity service. Nothing was revoked; retry.

So to "log out everywhere" and then tell a deleted user from a live one, read the status: 204 is a user of yours (with or without sessions), 403 is not a user of yours, and that includes one you deleted. Treat 403 after your own delete as "already gone".

(Until October 2026 a user who had never had a session got 404 here, and only after a first revocation did the call succeed.)

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 sessions; revoked ones come back too, with active: false
const res = await fetch(`/v1/gate/identities/${userId}/sessions`, {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const sessions = (await res.json()).filter((s) => s.active)

// 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).
Revoking a session does not recall a signed token (JWT) already issued from it: it keeps verifying until its own exp, at most 15 minutes after it was issued.
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.