OpenMax
免费试用

Apps API · Invitations

Invitations: 6 个接口

← 全部分组

GET /api/v1/invitations

List invitations

权限(scope): org:invitation:read · 调用方式: appToken · operationId: list-invitations

Required app scope: org:invitation:read.

Returns a paginated list of invitations. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
page query integer (int32) Page number (default: 1)
page_size query integer (int32) Items per page (default: 20, max: 100)
order_by query string Sort expression, e.g. created_at:desc
status query string Filter by status: pending, accepted, revoked, or expired (omit for all)

回包

POST /api/v1/invitations

Create an invitation

权限(scope): org:invitation:write · 调用方式: appToken · operationId: create-invitation

Required app scope: org:invitation:write.

Invites a new member to join the organization. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
Accept-Language header string Preferred invitation email language: en or zh (default: bilingual)

请求体

application/json · CreateInvitationRequestBody

字段 类型 必填 说明
display_name string 是 Invitee's org-level member display name
email string (email) Invitee email (for human invitations). Omit for agent invitations — use the returned token for programmatic delivery.
message string Optional invitation message
phone_cc string Invitee phone country calling code, digits only, no '+' (e.g. '86'). Paired with phone_number.
phone_number string Invitee national phone number without the country code. Paired with phone_cc.
role_id string (uuid) 是 Initial role to assign upon acceptance

回包

DELETE /api/v1/invitations/{invitation_id}

Revoke an invitation

权限(scope): org:invitation:write · 调用方式: appToken · operationId: revoke-invitation

Required app scope: org:invitation:write.

Revokes a pending invitation.

参数

名字 位置 类型 必填 说明
invitation_id path string (uuid) 是 Invitation UUID

回包

  • 204 No Content
  • default Error — application/problem+json · D8Error

POST /api/v1/invitations/{invitation_id}/accept

Accept an invitation

权限(scope): org:invitation:accept · 调用方式: appToken · operationId: accept-invitation

Required app scope: org:invitation:accept.

Accepts a pending invitation. Idempotent: if the caller already accepted this invitation and is still an active member of its org, this replays the original {member_id, org_id, role_slug} with 200 instead of failing, so revisiting an invite link is safe. role_slug reports the member's current role, which may differ from the role the invitation proposed. Revoked, expired, or never-joined cases still fail with INVITATION_NOT_ACCEPTABLE. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
Accept-Language header string Preferred language; the primary tag is captured as the identity locale (en or zh) if not already set
invitation_id path string (uuid) 是 Invitation UUID

请求体

application/json · AcceptInvitationRequestBody

字段 类型 必填 说明
token string Invitation token (for token-based acceptance, e.g. agent invitations)

回包

GET /api/v1/me/invitations

List invitations addressed to me

权限(scope): org:invitation:read · 调用方式: appToken · operationId: list-my-invitations

Required app scope: org:invitation:read.

Returns the open invitations addressed to one of the caller's VERIFIED login emails (password-registration email or an SSO email the provider asserted as verified; matched case-insensitively, surrounding spaces ignored; the self-entered profile contact address never counts), across organizations. Identity-level: works with an identity-only JWT (no organization yet) and with an org-scoped JWT; the identity always comes from the token. Open = still pending (not accepted, not revoked) with expires_at in the future, organization not deleted and not being deleted. Only email-only invitations are listed (no phone, agent or link invitations); organizations the caller is already a non-departed member of (including suspended) are skipped. At most one invitation per organization — the newest by created_at. org_name and inviter_display_name are current values. No side effects. Agent principals get 403. Response wrapped in standard envelope.

回包

POST /api/v1/me/invitations/{invitation_id}/accept

Accept an invitation addressed to me (no token)

权限(scope): org:invitation:accept · 调用方式: appToken · operationId: accept-my-invitation

Required app scope: org:invitation:accept.

Accepts, without the emailed token, an invitation addressed to one of the caller's VERIFIED login emails (same rule as GET /api/v1/me/invitations). Same result and idempotency as POST /api/v1/invitations/{invitation_id}/accept: 200 {member_id, org_id, role_slug}; replaying an invitation this caller already accepted returns the original membership; other pending invitations to the same address in that organization are revoked. Errors: 400 INVITATION_NOT_ACCEPTABLE (unknown id, not an email-only invitation, revoked, expired), 403 INVITATION_RECIPIENT_MISMATCH (not addressed to a verified email of the caller), 404 ORG_NOT_FOUND (the invitation is addressed to the caller and still pending, but its organization has been deleted — checked only after the recipient check, so other callers get 403/400 and never learn whether the organization exists; the token accept endpoint keeps answering 400 INVITATION_NOT_ACCEPTABLE here), 409 ORG_SEAT_LIMIT_REACHED, 409 ORG_ALREADY_MEMBER; agent principals 403. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
Accept-Language header string Preferred language; the primary tag is captured as the identity locale (en or zh) if not already set
invitation_id path string (uuid) 是 Invitation UUID from GET /api/v1/me/invitations

回包