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 own role.

Authorizations

• ClerkSession

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.

integer

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

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

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

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

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

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

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

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