创建用户

POST/v2/users

新建平台账号，可选直接发送激活邮件。

创建成功后账号处于 pending 状态，用户通过激活链接设置密码后转为 active。若 send_activation 为 false，需调用重置密码接口获取一次性激活令牌。

Bearer Token users:write api.demo.acme-cloud.dev

请求参数

共 1 项

Idempotency-Key 可选请求头

string

幂等键，24 小时内相同键返回同一结果

请求体

application/json

email 必填

string

登录邮箱，全局唯一

display_name 必填

string

显示名称，1–64 字符

password 可选

string

初始密码；省略则走邮件激活流程

roles 可选

array<string> · 默认 [ "member" ]

角色列表

可选值adminmemberviewer

org_id 可选

string

归属组织 ID，省略则使用调用者所在组织

send_activation 可选

boolean · 默认 true

是否立即发送激活邮件

profile 可选

object

扩展档案

locale 可选

string · 默认 zh-CN

语言偏好

timezone 可选

string · 默认 Asia/Shanghai

IANA 时区

响应

4 种状态

201 Created —— 创建成功

响应示例

{
  "id": "user_9d21c4",
  "email": "grace@acme.com",
  "display_name": "Grace Hopper",
  "status": "pending",
  "roles": [
    "member"
  ],
  "created_at": "2026-10-16T07:10:22Z"
}

代码示例

cURL

curl -i -X POST 'https://api.demo.acme-cloud.dev/v2/users' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: c1f9-4b2a-8e77' \
  -d '{
  "email": "grace@acme.com",
  "display_name": "Grace Hopper",
  "roles": [
    "member"
  ],
  "send_activation": true,
  "profile": {
    "locale": "zh-CN",
    "timezone": "Asia/Shanghai"
  }
}'

注意事项

强烈建议携带 Idempotency-Key，网络重试不会产生重复账号。