Accept an invitation (identity-only; email-bound)

POST

/v1/admin/invitations/accept

• Production
• Local

Accepts an invitation by its raw token. IDENTITY-ONLY (no {org_id}; the token carries the org). The accept binds to the authenticated user’s VERIFIED Clerk email == the normalized invitation email (else 403). Idempotent for the same user; a revoked/expired invitation cannot be accepted.

Authorizations

• ClerkSession

Request Body ^required

Accept an invitation with its raw token. IDENTITY-ONLY: the accept binds to the authenticated user’s VERIFIED Clerk email, which must equal the normalized invitation email (else 403). Idempotent for the same user.

object

token

required

string

Responses

200

Accepted (membership written).

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