Revoke an organization's sessions
POST /v1/organizations/{org_id}/sessions:revoke · permission sessions:write
Revokes every active session opened in the organization's context, for all of its users, together with the refresh token families issued for the organization or bound to those sessions. Access tokens issued for the organization stop being accepted by introspection and the revocation check from that moment. Use it after a security incident or when an organization is being offboarded; to sign out a single user or session, use Revoke a user's sessions.
The body must carry a reason. It is stored as a note on the management audit record only; the sessions themselves end with the revocation reason admin. Sessions that are already revoked or expired are not counted, so a repeated call succeeds with zero counts. Send an Idempotency-Key header to make retries safe.
Request
| Parameter | In | Required | Description |
|---|---|---|---|
org_id |
path | yes | Organization id, prefixed org_. |
Body:
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string | yes | Your note for the audit log: 1-256 characters, no control characters or line breaks. |
Response
200 OK.
{
"revoked_sessions": 42,
"revoked_token_families": 57
}
| Field | Description |
|---|---|
revoked_sessions |
Sessions revoked by this call. |
revoked_token_families |
Refresh token families revoked by this call. |
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 |
reason is missing or empty (required), longer than 256 characters (too_long) or holds a control character or line break (invalid_value). |
| 404 | not_found |
The organization does not exist in this environment. |
| 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/organizations/org_0a1b2c3d4e5f6g7h8j9k0m1n2p/sessions:revoke \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "Security incident INC-1042"}'
CLI: keenauth organizations sessions revoke org_0a1b2c3d4e5f6g7h8j9k0m1n2p --reason "Security incident INC-1042" --yes