# 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](../users/revoke-sessions.md).

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`.

```json
{
  "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

```bash
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`