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:
pendingtoactive, which approves the accountactivetodisabledorarchiveddisabledtoactiveorarchivedarchivedtoactive, 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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The account’s ref, from GET /admin/users.
Request Body required
Section titled “Request Body required ”object
The status to move the account to.
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.
Responses
Section titled “ Responses ”The result; changed says whether the status changed.
object
The account’s number.
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.
The status the update found stored when it ran.
true if this request wrote the new status, false if the stored
status already matched.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed