Identity & Access Management

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

POST
/scopes/{scopeId}/iam/users/{userId}/invites

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

userId*string

Identifier of the IAM user.

Header Parameters

Idempotency-Key*string

Required: 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.

Formatuuid

Request Body

application/json
  1. body

Optional payload when sending or resending an invitation.

personalMessage?string

Optional plain-text message prepended to the invitation email (at most 500 characters, no links).

Lengthlength <= 500
locale?|

Console locale for the invitation link (tr, en, de); unsupported values fall back to the default.

Response Body

Invitation accepted; invite resource in its transitional PENDING state.

application/json
  1. response

Invitation record for a user; new invites supersede previously issued links.

id*string

Invite identifier.

userId*string

User the invite belongs to.

email*string

Address the invitation is sent to.

status*string

Invite lifecycle state.

Value in"PENDING""SENT""ACCEPTED""EXPIRED""FAILED"
sentAt*|

When the email was dispatched; null while PENDING.

Formatdate-time
expiresAt*string

When the sign-in link expires.

Formatdate-time
message*|

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"}