Delete (Deactivate) / Restore User
DELETE/api/users/:user
Toggles user activation status, scoped to the current tenant.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Delete (user not trashed): detaches the tenant_users pivot row for the current tenant. If the user has no remaining pivot rows after the detach, the central users row is soft-deleted as well; otherwise the central row stays intact so the user remains usable in other tenants.
Restore (user trashed): re-attaches the pivot row for the current tenant (mirroring central's is_admin / is_power_user flags) and un-soft-deletes the central row. Restore is allowed when the user is already attached here OR is fully orphaned (no pivot rows anywhere). Restoring a user whose only pivots are to OTHER tenants is rejected (404) to prevent cross-tenant claim attacks.
Tenant scoping: Returns 404 if the user is not a member of the current tenant on the delete path. Prevents any tenant admin from deactivating users system-wide by guessing IDs.
Authentication: Requires Bearer token.
Requires permission: users.delete
Request
Responses
- 200
- 401
- 403
- 404
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.