Execute an operation-bound Agent user suspension.

POST

/api/admin/agent-write/users/{id}/suspend

Code sample: Shell / cURL

curl --request POST \
  --url https://auth.example.com/api/admin/agent-write/users/example/suspend \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "reason_code": "policy_violation", "duration_hours": 1, "revoke_tokens": true, "revoke_sessions": true, "notify_user": false }'

Owner-package mutation endpoint for the fixed admin.write.users.suspend operation. Requires an Agent downscope token carrying admin:users:suspend; the Agent Access server invokes it only after consuming an approved argument-bound elevation capability and sends the server-issued Idempotency-Key. Free-form reason detail is not accepted by the MCP Tool.

Authorizations

• adminBearer

Parameters

Path Parameters

id

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9._~-]+$/

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 256 characters

Request Body ^required

Media type application/json

object

reason_code

required

string

Allowed values: policy_violation security_incident account_abuse payment_issue user_request admin_action investigation compliance other

duration_hours

integer

>= 1 <= 8760

revoke_tokens

boolean

default: true

revoke_sessions

boolean

default: true

notify_user

boolean

key

additional properties

Responses

200

User suspension reached a definite terminal result.

Media type application/json

object

user_id

required

string

status

required

string

Allowed value: suspended

previous_status

required

string

effective_at

required

string format: date-time

expires_at

string format: date-time

reason_code

required

string

revoked

required

object

key

additional properties

Example

{
  "status": "suspended"
}

400

Error response.

Media type application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

401

Error response.

Media type application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

403

Error response.

Media type application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

404

Error response.

Media type application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

409

Error response.

Media type application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Encryption or terminal-result persistence is unavailable. The X-Authrim-Execution-Indeterminate response header means the caller must not retry automatically.

Media type application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

Headers

X-Authrim-Execution-Indeterminate

string

Allowed values: true