Revoke a user's sessions

POST /v1/users/{user_id}/sessions:revoke · permission sessions:write

Revokes the user's sessions and the refresh token families bound to them; access tokens they issued stop being accepted by introspection and the revocation check. Without a body (or with {}) every session of the user is revoked. At most one filter may be given:

session_id: only that session (it must belong to the user, otherwise 404).
org_id: the sessions opened in that organization's context and the user's refresh token families for that organization.
client_id: only that application's refresh token families for this user; the sessions stay open. Use the application id (app_…); the URL-form client_id of a Client ID Metadata Document application is not accepted.

Sessions that are already revoked or expired are not counted, so a repeated call succeeds with zero counts. Every revocation is written to the management audit log. Send an Idempotency-Key header to make retries safe.

Request

Parameter	In	Required	Description
`user_id`	path	yes	User id, prefixed `usr_`.

Optional body (at most one field):

Field	Type	Required	Description
`session_id`	string	no	Session id, prefixed `ses_`.
`org_id`	string	no	Organization id, prefixed `org_`.
`client_id`	string	no	Application id, prefixed `app_`.

Response

200 OK.

{
  "revoked_sessions": 2,
  "revoked_token_families": 3
}

revoked_sessions is 0 with client_id (sessions stay open).

Errors

Every error is an application/problem+json body with a stable code.

HTTP	`code`	When
400	`malformed_request`, `unknown_field`	The body is not valid JSON or has an unknown field.
415	`unsupported_media_type`	A body was sent without `Content-Type: application/json`.
422	`validation_failed`	More than one filter (`mutually_exclusive`), a malformed id (`invalid_value`), or the organization or application does not exist in this environment (`not_found` at `/org_id` or `/client_id`).
404	`not_found`	The user does not exist in this environment, or `session_id` is not one of the user's sessions.
401	`unauthenticated`	The API key is missing, invalid or revoked.
403	`insufficient_permissions`	The key lacks the `sessions:write` permission.
429	`rate_limited`	The rate limit was exceeded; honor `Retry-After`.
503	`service_unavailable`	A dependency is temporarily unavailable; retry later.

Example

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/sessions:revoke \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org_0a1b2c3d4e5f6g7h8j9k0m1n2p"}'

CLI: keenauth users sessions revoke usr_0a1b2c3d4e5f6g7h8j9k0m1n2p --org-id org_0a1b2c3d4e5f6g7h8j9k0m1n2p --yes