API Reference
InvitesEnterprise
Inviting people to the account, and changing, resending and revoking invitations.
The invites endpoints invite people to the account by email, with an account role and access to organizations. They need a key of the account organization, and keys limited to some routers cannot use them. See Inviting People.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/people/invites | List invitations. Filter with status: pending, accepted, declined, revoked or expired. Paginated. | invites:read |
| POST | /v1/people/invites | Invite a person. Returns 201. Accepts an Idempotency-Key. | invites:write |
| GET | /v1/people/invites/{id} | Get one invitation. | invites:read |
| PATCH | /v1/people/invites/{id} | Change account_role or grants of a pending invitation. Accepts dry_run. | invites:write |
| DELETE | /v1/people/invites/{id} | Revoke an invitation. | invites:delete |
| POST | /v1/people/invites/{id}/resend | Renew a pending invitation for seven days and email it again. Takes no body. Accepts an Idempotency-Key. | invites:write |
A create requires email, account_role (admin, member or null, and present even when null), and grants, each with organization_id, role (admin, member or null), managed and policy_id. In a PATCH, account_role: null clears the account role, while grants: null leaves grants unchanged; grants: [] clears them. Creates and resends share a budget of 20 attempts per minute per account; an idempotent replay of a resend does not count or send again.
| Code | Status | Meaning |
|---|---|---|
invalid_account_role | 400 | The account role is not admin, member or null. |
invalid_grants | 400 | A grant is invalid. |
account_organization_role_mismatch | 400 | The grant for the account organization has a role that differs from account_role. |
account_token_required | 403 | The key belongs to a named organization. |
router_scoped_token | 403 | The key is limited to some routers. |
invite_not_found | 404 | No invitation has that id. |
person_exists | 409 | The person already belongs to the account. |
invite_pending | 409 | A pending invitation for the email already exists. |
invite_not_pending | 409 | A change or resend names an invitation that is not pending. |
invite_changed | 409 | The invitation changed at the same time. Retry. |
rate_limited | 429 | Over 20 invite attempts per minute. Retry-After gives the seconds to wait. |