Create invite

POST/v1/invites

Accepts bearer

Invite a colleague into the tenant

Needs users:manage, which no API key can hold.Show more

Needs users:manage, which no API key can hold. The permissions granted must be a subset of the inviter's; the invitee joins the site the inviter is signed in to. The invite token goes to the invitee only — it is never in this response — and is valid for 7 days, once. invite by role. The body carries exactly one of role (a ConsoleRole) or permissions; both or neither is 400 VALIDATION details.field role (the backend enforces it, no oneOf). With role the invitee is granted that role's permission bundle intersected with the permissions the inviter holds: a permission the inviter lacks is dropped, never granted, and the 201 permissions list exactly what was granted (role echoes the role). Inviting as OWNER needs an Owner. With permissions, as before.

Request bodyInviteRequest

emailstring · emailRequired
permissionsarray of stringOptional
A subset of the inviter's permissions
rolestringOptional
Permissions are resolved from the role bundle by the platform; a client reads `permissions`, never derives them.
- OWNER
- ADMIN
- DEVELOPER
- OPS_AGENT
- FINANCE
- REVENUE_MANAGER
- CONTENT_EDITOR
- AUDITOR

Responses

201InvitedInvited
400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
401
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
ApiErrorResponse
403
The 403s of the credential-issuing routes (POST /v1/keys, POST /v1/keys/{keyPrefix}/rotate, POST /v1/invites).Show more
The 403s of the credential-issuing routes (POST /v1/keys, POST /v1/keys/{keyPrefix}/rotate, POST /v1/invites). PERMISSION_DENIED when the caller lacks keys:manage / users:manage, and on the key routes also when a live key is asked for a tenant that is not LIVE or is a sandbox twin. On POST /v1/keys also PERMISSION_DENIED with details.reason SYSTEM_KEY_REQUIRES_ADMIN when actorKind is system and the caller is not a tenant admin.
ApiErrorResponse
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
413
VALIDATION — the request body is larger than the surface's limit.Show more
VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
ApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
415
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
501
NOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug.Show more
NOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug. Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) on a deployment with no order reader assembled; not retryable.
ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400	VALIDATION message.intent.checkOut must be after message.intent.checkIn	not retryable
400	UNKNOWN_DOMAIN Unknown domain 'HOTELS'. Did you mean HTL?	not retryable
401	UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry.	not retryable
403	PERMISSION_DENIED Inviting colleagues needs the users:manage permission.	not retryable
403	TENANT_SUSPENDED This tenant is suspended; no key can be minted or rotated until it is reinstated. Existing keys can still be revoked.	not retryable
405	VALIDATION This method is not served.	not retryable
413	VALIDATION The request body is larger than this API accepts (262144 bytes).	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
415	VALIDATION Send application/json.	not retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable
501	NOT_IMPLEMENTED seatmap is NOT_APPLICABLE for HTL; GET /v1/capabilities says so	not retryable