Block a user

POST /v1/users/{user_id}:block · permission users:write

Blocks a user with a customer block (source = admin_api); the status becomes blocked. Blocking a user that is already blocked succeeds without a change. A user that is pending deletion cannot be blocked. Revoking the user's sessions runs asynchronously. Send an Idempotency-Key header to make retries safe.

Request

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

Optional body:

Field	Type	Required	Description
`note`	string	no	Up to 1000 characters. Do not write personal data.

Response

200 OK. The body is the user object. The ETag header carries the user version.

Personal data is masked when the key lacks the users:read_pii permission: email becomes a***@e***.com, phone_number keeps only its last 2 digits (+**********67), name, given_name, family_name, middle_name and nickname become initials (A. L.), username keeps only its first character (a***), birthdate becomes ****-**-** and address becomes {"redacted": true}. user_metadata and app_metadata are not masked.

{
  "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "kind": "regular",
  "status": "active",
  "external_id": null,
  "username": null,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "email_verified": true,
  "phone_number": null,
  "phone_verified": false,
  "user_metadata": {},
  "app_metadata": {},
  "created_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "last_sign_in_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null
}

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.
409	`conflict`	The user is pending deletion (`errors[].code` is `user_pending_deletion`).
415	`unsupported_media_type`	A body was sent without `Content-Type: application/json`.
422	`validation_failed`	`note` is too long.
404	`not_found`	The user does not exist in this environment (or the id is malformed).
401	`unauthenticated`	The API key is missing, invalid or revoked.
403	`insufficient_permissions`	The key lacks the `users: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:block \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"note": "Suspected account takeover"}'

Personal data

This endpoint carries personal data: end-user profile. Personal data in the KeenAuth APIs describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.