Auth API reference

Auth API · Consumer-Tenants

post/{app_slug}/v1/tenants/{tenant_id}/invitesAuth

Invite an email address into a tenant. Mints a pending invite, mails the code through the app's `invite_template_name` Envoi slot, and returns the plaintext code ONCE. PAK must hold auth.tenant.members.add.

Unlike `POST /members`, nothing is granted until the invitee accepts at `POST /:appSlug/v1/auth/accept-tenant-invite`. Only a SHA-256 digest of the code is stored, so the `code` in this response is unrecoverable afterwards.

Path parameters

app_slug*string

Slug of the app.

tenant_id*string

Id of the tenant.

Headers

Idempotency-Keystring

Retry safety: a repeat with the same key and body replays the first response instead of creating an invite again. Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.

Request body

email*string

Address the invite is bound to. The account created on accept gets this as its verified primary email, so it cannot be changed after mint — revoke and re-invite instead.

Example: "alice@example.com"

namestring

Human-readable name rendered in the invite email.

Example: "Alice Wong"

role_name*string

Tenant-scoped role granted on accept. Case-insensitive lookup against this app's `role` table.

Example: "member"

max_usesnumber

Number of times the code may be redeemed. Defaults to 1. Values above 1 only matter for a code you intend to hand out manually — the first acceptance consumes the email binding, so a second accept of the same address is rejected regardless.

expires_in_hoursnumber

Hours until the invite expires. Defaults to 168 (7 days).

Response · 201 Pending invite. `code` appears here and nowhere else.

id*string

Unique identifier of the tenant invite.

tenant_id*string

The tenant the tenant invite belongs to.

email*string

Email address.

Example: "alice@example.com"

role_id*string

Id of the role.

role_name*string

Name of the role.

Example: "member"

status*object

Derived, never stored: revoked > expired > used > pending.

max_uses*number

How many times the tenant invite can be used, or `null` for no limit.

Example: 1

use_count*number

How many times the tenant invite has been used.

Example: 0

expires_at*string · date-time

When the tenant invite expires (ISO 8601), or `null` if it never does.

revoked_at*string · date-time

When the tenant invite was revoked (ISO 8601), or `null` while it is active.

invited_by*string

Account id of the inviter. Null when the invite was minted by a Platform API Key, which has no account row — the audit log carries that attribution instead.

created_at*string · date-time

When the tenant invite was created (ISO 8601).

code*string

The plaintext invite code, returned EXACTLY ONCE. Only its SHA-256 digest is stored, so this value cannot be recovered from the list endpoint or the database — if you lose it, revoke the invite and mint a new one. It is also mailed to the invitee through the app's `invite_template_name` Envoi slot.

Example: "tinv_9dK2mQ7pR4vXbN1sT6yZ0hLcJeW3fAgU"

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/tenants/{tenant_id}/invites
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "email": "alice@example.com",
  "name": "Alice Wong",
  "role_name": "member",
  "max_uses": 0,
  "expires_in_hours": 0
}

Response

{
  "id": "string",
  "tenant_id": "string",
  "email": "alice@example.com",
  "role_id": "string",
  "role_name": "member",
  "status": {},
  "max_uses": 1,
  "use_count": 0,
  "expires_at": "2026-01-01T00:00:00.000Z",
  "revoked_at": "2026-01-01T00:00:00.000Z",
  "invited_by": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "code": "tinv_9dK2mQ7pR4vXbN1sT6yZ0hLcJeW3fAgU"
}