Soft-delete a KYC user (sets is_active=False).
Does not touch kyc_status or the verification provider applicant. Deactivated
users are hidden from the default GET /lists response unless the
caller passes include_inactive=true. Idempotent: re-deactivating
an already-inactive user is a no-op success.
require_client_permissions enforces allowed_roles only for
client_user actors; the explicit role guard below also rejects
client_api callers whose credential role is not Owner.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Deactivate (soft-delete) a KYC user. The user is marked inactive (is_active = false) and the supplied reason is recorded in the audit log. This does not change the user's kyc_status or remove any verification records. Deactivated users are excluded from the default GET /api/v1/kyc/users listing unless that request is made with include_inactive=true. The endpoint returns the updated user record.
The operation is idempotent: deactivating a user that is already inactive succeeds and returns the current record without writing a new audit entry.
Authentication & access
- Requires a client token:
Authorization: Bearer <token>. - The caller must hold the
kyc.users.writepermission. - The action is restricted to the OWNER role. Callers with any other role are rejected with
403.
Path parameters
| Parameter | In | Description |
|---|---|---|
user_id | path | ID of the KYC user to deactivate. Must belong to your client. |
Request body
| Field | Type | Constraints | Description |
|---|---|---|---|
reason | string | required, 10–500 characters | Operational reason recorded in the audit log. The 10-character minimum ensures the audit trail captures meaningful context. |
Response
200 OK returns the updated UserResponse, including id, email, full_name, kyc_status, verification_mode, external_verification_status, verification_source, is_active (now false), and created_at. The kyc_status value is unchanged by this operation.
Error responses
| Status | When |
|---|---|
404 | No user with the given user_id exists under this client |
422 | Request body failed validation (e.g. reason shorter than 10 or longer than 500 characters, or missing) |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.