Change a user's lifecycle status (admin)

PUT

/admin/users/{ref}/status

• Local development behind nginx (port 8088 by default)

Admin-only lifecycle transition. Moves a user through pending / active / disabled. The audit log records the before / after / reason tuple.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

ref

required

integer format: int64

Request Body ^required

object

status

required

string

Allowed values: active pending disabled archived

reason

Free-text justification recorded in the audit log alongside the before/after pair. Encouraged but not required — an empty reason still produces an audit row.

string

<= 500 characters

Responses

200

New status (after the transition).

object

ref

required

integer format: int64

status

required

string

Allowed values: active pending disabled archived

previous_status

string

Allowed values: active pending disabled archived

changed

required

False when the target status equals the current status (the handler short-circuits the write but still returns 200 so idempotent automation doesn’t trip on a no-op).

boolean

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed