Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Send or resend an invitation to a user
Creates a new invitation for the selected user — the "Resend invite" action shown for INVITED
members in the Users page row menus and in the detail header. A fresh invitation email containing
the getting-started guide, the console URL and a sign-in link is dispatched to the user's
registered address; any previously issued invite link for the user is superseded. An optional
personal message is prepended to the email. The invite becomes discoverable on the user record
and the member remains INVITED until they accept.
Validation: userId must exist and be visible in scopeId (404 via ErrNotFound); the user
must currently be in INVITED state — resending to an ACTIVE or INACTIVE member is rejected with
409 CONFLICT; personalMessage, when provided, is length-bounded (422 VALIDATION_FAILED on
overflow); the caller must hold owner|admin on the scope.
Async & state: Asynchronous — returns 202 with the Invite resource in its transitional
PENDING state; email dispatch moves it to terminal SENT (or FAILED on delivery error), and
acceptance later transitions it to ACCEPTED while flipping the user to ACTIVE. Progress is
pushed via resource.updated SSE frames (kind iam.userInvite, patch on status; the parent
iam.user frame patches status on acceptance).
Errors: 401 unauthenticated; 403 when the caller lacks owner|admin on the scope; 404 when
scopeId/userId is unknown; 409 when the user is not in an invitable state; 422 on body
validation failure (a personalMessage over 500 characters or carrying a link); 429 when
invitation sending is rate-limited (details.reason: INVITE_RESEND_COOLDOWN
within 60 s of the last invite, INVITE_USER_DAILY_LIMIT after 5 in 24 h,
INVITE_TENANT_DAILY_LIMIT for the tenant's daily budget); 500 on dispatch failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the
originally created invite without sending a duplicate email — duplicate invitations would be
harmful, so retries are made safe.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
userId*stringIdentifier of the IAM user.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
Optional payload when sending or resending an invitation.
personalMessage?stringOptional plain-text message prepended to the invitation email (at most 500 characters, no links).
length <= 500locale?|Console locale for the invitation link (tr, en, de); unsupported values fall back to the default.
Invitation accepted; invite resource in its transitional PENDING state.
application/json- response
Invitation record for a user; new invites supersede previously issued links.
id*stringInvite identifier.
userId*stringUser the invite belongs to.
email*stringAddress the invitation is sent to.
status*stringInvite lifecycle state.
"PENDING""SENT""ACCEPTED""EXPIRED""FAILED"sentAt*|When the email was dispatched; null while PENDING.
date-timeexpiresAt*stringWhen the sign-in link expires.
date-timemessage*|Personal message included in the email; null when none.
curl -X POST "https://example.com/scopes/string/iam/users/string/invites" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "string", "userId": "string", "email": "string", "status": "PENDING", "sentAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "message": "string"}