Apps API · Invitations
Invitations: 6 endpoints
GET /api/v1/invitations
List invitations
Scope: org:invitation:read · Called with: appToken · operationId: list-invitations
Required app scope: org:invitation:read.
Returns a paginated list of invitations. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
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) |
Responses
200OK —application/json·PageListResponseInvitationSummaryBodydefaultError —application/problem+json·D8Error
POST /api/v1/invitations
Create an invitation
Scope: org:invitation:write · Called with: appToken · operationId: create-invitation
Required app scope: org:invitation:write.
Invites a new member to join the organization. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Accept-Language |
header | string | Preferred invitation email language: en or zh (default: bilingual) |
Request body
application/json · CreateInvitationRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
display_name |
string | yes | 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) | yes | Initial role to assign upon acceptance |
Responses
200OK —application/json·DataResponseCreateInvitationDataBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/invitations/{invitation_id}
Revoke an invitation
Scope: org:invitation:write · Called with: appToken · operationId: revoke-invitation
Required app scope: org:invitation:write.
Revokes a pending invitation.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
invitation_id |
path | string (uuid) | yes | Invitation UUID |
Responses
204No ContentdefaultError —application/problem+json·D8Error
POST /api/v1/invitations/{invitation_id}/accept
Accept an invitation
Scope: org:invitation:accept · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
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) | yes | Invitation UUID |
Request body
application/json · AcceptInvitationRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
token |
string | Invitation token (for token-based acceptance, e.g. agent invitations) |
Responses
200OK —application/json·DataResponseAcceptInvitationDataBodydefaultError —application/problem+json·D8Error
GET /api/v1/me/invitations
List invitations addressed to me
Scope: org:invitation:read · Called with: 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.
Responses
200OK —application/json·DataResponseListMyInvitationsDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/me/invitations/{invitation_id}/accept
Accept an invitation addressed to me (no token)
Scope: org:invitation:accept · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
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) | yes | Invitation UUID from GET /api/v1/me/invitations |
Responses
200OK —application/json·DataResponseAcceptInvitationDataBodydefaultError —application/problem+json·D8Error
