Invite a member to the org (admin; role-capped)

POST

/v1/admin/orgs/{org_id}/invitations

• Production
• Local

Creates (or idempotently reuses an existing pending) org invitation. The raw token is returned ONCE on a fresh create (201); a reused pending invite returns 200 with no token. Role-capped to the inviter’s current role. Fresh creates queue an email transactionally; identical pending creates do not resend. Changed-role duplicates conflict. Pending invitations reserve no seats, so creation is allowed at capacity. Acceptance atomically checks joined distinct people against the billing root’s member limit. Limits are 100 pending invitations per org, 50 dispatches per org/hour, and 60 seconds between sends of one invitation.

Authorizations

• ClerkSession
• AgentKey
  account:admin

Parameters

Path Parameters

org_id

required

string

Request Body ^required

Invite an email to the org. Role-capped: the inviter cannot grant a role above their own effective role. Idempotent: one pending invitation per (org, email). The raw token is returned ONCE on a fresh create.

object

email

required

string format: email

role

required

string

Allowed values: owner admin member viewer billing

expires_in_days

Optional TTL in days; omitted or zero means 14.

integer

<= 30

Responses

200

Existing pending invitation reused (no new token).

An org invitation. token is the raw secret returned ONCE on a fresh create (empty when an existing pending invitation was reused, or on accept/revoke).

object

gift

object

gift_code

string

<= 64 characters

redeem_before

string format: date-time

status

required

Pending_human_claim is not Startup activation. No card is required to claim a gift.

string

campaign_id

string

claim_id

string

ends_at

string format: date-time

id

required

string

org_id

required

string

email

required

string

role

required

string

Allowed values: owner admin member viewer billing

status

required

string

Allowed values: pending accepted revoked expired

organization_name

string

invite_url

Sign-in link; possession grants no access.

string

delivery_state

Email dispatch status; submitted does not confirm receipt.

string

Allowed values: queued submitted failed cancelled not_recorded

last_blocked_at

string format: date-time

token_prefix

required

string

token

Raw invitation token; present only on a fresh create.

string

expires_at

required

string format: date-time

created_at

required

string format: date-time

201

Created (raw token shown once).

An org invitation. token is the raw secret returned ONCE on a fresh create (empty when an existing pending invitation was reused, or on accept/revoke).

object

gift

object

gift_code

string

<= 64 characters

redeem_before

string format: date-time

status

required

Pending_human_claim is not Startup activation. No card is required to claim a gift.

string

campaign_id

string

claim_id

string

ends_at

string format: date-time

id

required

string

org_id

required

string

email

required

string

role

required

string

Allowed values: owner admin member viewer billing

status

required

string

Allowed values: pending accepted revoked expired

organization_name

string

invite_url

Sign-in link; possession grants no access.

string

delivery_state

Email dispatch status; submitted does not confirm receipt.

string

Allowed values: queued submitted failed cancelled not_recorded

last_blocked_at

string format: date-time

token_prefix

required

string

token

Raw invitation token; present only on a fresh create.

string

expires_at

required

string format: date-time

created_at

required

string format: date-time

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean