Skip to content

Change a user's account status

PUT
/admin/users/{ref}/status

Approves, disables, archives or restores a user’s account by changing its status.

These changes are allowed:

  • pending to active, which approves the account
  • active to disabled or archived
  • disabled to active or archived
  • archived to active, which restores it

Sending the status the account already has returns 200 with changed: false and does nothing else. Any other change gets 400: to disable a pending account, approve it first. Moving the only system administrator out of active is also refused with 400; grant system.admin to someone else first.

Both checks are best effort. They run before the change is written, against a status that may be cached, so a stale status or another change at the same moment can get past them. The administrator check also doesn’t recognise system.admin held only through an inherited role.

You need users.approve, which is separate from users.read and users.write; system.admin also works. An unknown user gets 404.

Status is checked when someone signs in, not when a session or API token is used. Disabled and archived accounts can’t sign in; pending ones can, with whatever their roles allow. Moving an active account to disabled or archived also ends all of its sessions, but if that step fails the new status still stands. Its API tokens aren’t revoked and keep working, and only their owner can revoke them. Roles, lockouts, expiry and email verification are left as they are.

Archiving keeps the account and its content, but a daily cleanup can delete an account permanently once it has been archived for longer than the user retention period (90 days by default).

Each change is recorded in the audit log on a best-effort basis, with your reason, as user.status_changed plus one of admin.users.approved, admin.users.disabled, admin.users.archived or admin.users.restored. A change refused because of the last administrator is recorded too, on the same best-effort basis, as admin.users.refused_last_admin with your reason. Other refusals, and a request for the status the account already has, record nothing.

ref
required
integer format: int64

The account’s ref, from GET /admin/users.

object
status
required

The status to move the account to.

string
Allowed values: active pending disabled archived
reason

An optional note saying why. It’s recorded with the audit events for the change, or for a refusal because of the last administrator, on a best-effort basis. A request for the status the account already has records nothing. The limit is 500 characters, though longer notes are currently accepted.

string
<= 500 characters

The result; changed says whether the status changed.

object
ref
required

The account’s number.

integer format: int64
status
required

The status you asked for. The account isn’t read again after the update, so a change someone else makes at the same moment won’t show here.

string
Allowed values: active pending disabled archived
previous_status

The status the update found stored when it ran.

string
Allowed values: active pending disabled archived
changed
required

true if this request wrote the new status, false if the stored status already matched.

boolean

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed