Update a user (displayName, state, email)..

PATCH

/v1/iam/users/{userId}

Code sample: Shell / cURL

curl --request PATCH \
  --url https://stratum.example.com/v1/iam/users/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "displayName": "example", "state": "active", "email": "hello@example.com" }'

• A Stratum cluster endpoint.

Sparse PATCH — nil fields are left alone, non-nil fields are applied. Mutable fields:

• displayName — free-form, non-empty.
• state — active or suspended. Soft-delete uses the DELETE verb, not state mutation.
• email — the sign-in address. Install admins only: also needs iam:UpdateUserEmail on the install (an install-scope PAT, as the Stratum Account portal uses, qualifies). Trimmed and lower-cased like create; unique among live users (a deleted user’s address is free). Sessions and PATs are kept; the next password login uses the new address. An OIDC-linked user keeps signing in: the link is by the provider’s subject, not the email, and a login never rewrites the address. Audited as iam.user.updated (with email + previousEmail) and iam.user.email_changed.

Suspend cascade: transitioning to state: suspended revokes every active session + PAT owned by the user in the same store transaction. The next API call from that user 401s within the auth-cache TTL (60s; usually < 1s on cache miss).

Reactivate: transitioning back to state: active re-enables login but does NOT restore the revoked tokens — the user must log in again to get a fresh session.

Refuses with 409 LAST_BOOTSTRAP_ADMIN if the body would suspend the user that holds the last install-scope bootstrap-admin binding — same lockout shape as DELETE.

Authorizations

• bearerAuth

Parameters

Path Parameters

userId

required

string

/^u-[a-z0-9-]+$/

Request Body^required

Media typeapplication/json

Sparse PATCH body for ’s PATCH /v1/iam/users/{userId}. Every field is optional; the caller must set at least one. Empty strings are rejected. state only accepts active or suspended — soft-delete uses the DELETE verb, and pending is not a settable target.

object

displayName

string

>= 1 characters <= 100 characters

state

string

Allowed values: active suspended

email

New sign-in address. Install admins only (iam:UpdateUserEmail on the install). Normalized (trimmed, lower-cased); 409 EMAIL_TAKEN when another live user has it. Sessions and PATs are kept.

string format: email

<= 254 characters

Responses

200

The updated user.

Media typeapplication/json

object

id

required

string

/^u-[a-z0-9-]+$/

email

required

string format: email

displayName

required

string

state

required

string

Allowed values: pending active suspended deleted

lastLoginAt

string format: date-time

nullable

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

createdBy

required

string

mfaEnabled

Whether the user has an active TOTP MFA enrollment..

boolean

passwordChangeRequired

. Present (true) on the login response and GET /v1/iam/me while the user still has the install-time password.

boolean

mfaEnrollmentRequired

. Present (true) on the login response and GET /v1/iam/me while a TOTP enrollment is owed after a node MFA recovery.

boolean

Example

{
  "state": "pending"
}

400

Bad request.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

401

Missing or invalid token.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

Headers

WWW-Authenticate

string

403

Authenticated but not authorized.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

404

Resource not found.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

409

Refused — would suspend the last install-scope bootstrap-admin (code: LAST_BOOTSTRAP_ADMIN), or email belongs to another live user (code: EMAIL_TAKEN).

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}