POST/api/v1/orgs/:orgId/invitations发起组织邀请

Try it 面板需要启用 JavaScript。

向手机号 / 邮箱发出一次性邀请（经 OTP 通道投递邀请令牌）；接受后自动授予指定角色。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	会话令牌认证，格式 `Bearer <sessionToken>`
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 会话令牌认证，格式 `Bearer <sessionToken>` */
  Authorization: string
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Authorization": "Bearer st_7c1f9e05b28d4a63",
  "Content-Type": "application/json"
}

URL Parameters

Name	Data Type	Description
orgId	string	组织 ID

Body

Name	Data Type	Required	Description
channel	string	Yes	通道：phone / email
target	string	Yes	被邀用户手机号 / 邮箱
roleIds	array	No	接受后授予的组织角色

type RequestBody = {
  /** 通道：phone / email */
  channel: string
  /** 被邀用户手机号 / 邮箱 */
  target: string
  /** 接受后授予的组织角色 */
  roleIds?: string[]
}

{
  "channel": "email",
  "target": "liu.yang@example.com",
  "roleIds": [
    "01JD8SRR3N6V0X8ZS7X1ZFN4A9M"
  ]
}

Response

Body

InvitationDTO

Name	Data Type	Required	Description
invitationId	string	Yes	邀请 ID
orgId	string	Yes	目标组织 ID
channel	string	Yes	邀请通道：phone / email
target	string	Yes	被邀手机号 / 邮箱（脱敏）
invitorName	string	Yes	邀请人昵称
roleIds	array	No	接受后自动授予的角色
status	string	Yes	pending / accepted / expired
createdAt	string	Yes	创建时间
expiresAt	string	Yes	过期时间

type InvitationDTO = {
  /** 邀请 ID */
  invitationId: string
  /** 目标组织 ID */
  orgId: string
  /** 邀请通道：phone / email */
  channel: string
  /** 被邀手机号 / 邮箱（脱敏） */
  target: string
  /** 邀请人昵称 */
  invitorName: string
  /** 接受后自动授予的角色 */
  roleIds?: string[]
  /** pending / accepted / expired */
  status: string
  /** 创建时间 */
  createdAt: string
  /** 过期时间 */
  expiresAt: string
}

{
  "invitationId": "01JD8SRT5N8X2Z0BU9Y3BHK6C1O",
  "orgId": "01JD8SRP1N4T8W6XQ5V9XDL2Y7K",
  "channel": "email",
  "target": "liu.yang@example.com",
  "invitorName": "陈林",
  "roleIds": [
    "01JD8SRR3N6V0X8ZS7X1ZFN4A9M"
  ],
  "status": "pending",
  "createdAt": "2026-10-14T13:00:00Z",
  "expiresAt": "2026-10-17T13:00:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回新邀请
403	无权操作	需要组织管理权限
409	已是成员	该用户已在组织中

Response Code

响应使用统一信封 {id, code, messages, result}，其 code 字段：

code	Meaning	Notes
0	成功	返回新邀请
2501	无权操作组织	当前用户不持有组织管理权限
2504	用户已是成员	目标手机号 / 邮箱对应用户已在组织中

Examples

POST /api/v1/orgs/01JD8SRP1N4T8W6XQ5V9XDL2Y7K/invitations
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "channel": "email",
  "target": "liu.yang@example.com",
  "roleIds": ["01JD8SRR3N6V0X8ZS7X1ZFN4A9M"]
}

{
  "id": "01JD8SS2IV7G1I9KD",
  "code": 0,
  "messages": [],
  "result": {
    "invitationId": "01JD8SRT5N8X2Z0BU9Y3BHK6C1O",
    "orgId": "01JD8SRP1N4T8W6XQ5V9XDL2Y7K",
    "channel": "email",
    "target": "liu.yang@example.com",
    "invitorName": "陈林",
    "roleIds": ["01JD8SRR3N6V0X8ZS7X1ZFN4A9M"],
    "status": "pending",
    "createdAt": "2026-10-14T13:00:00Z",
    "expiresAt": "2026-10-17T13:00:00Z"
  }
}