/{app_slug}/v1/tenants/{tenant_id}/invitesAuthInvite 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*stringSlug of the app.
tenant_id*stringId of the tenant.
Headers
Idempotency-KeystringRetry 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*stringAddress 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"
namestringHuman-readable name rendered in the invite email.
Example: "Alice Wong"
role_name*stringTenant-scoped role granted on accept. Case-insensitive lookup against this app's `role` table.
Example: "member"
max_usesnumberNumber 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_hoursnumberHours until the invite expires. Defaults to 168 (7 days).
Response · 201 Pending invite. `code` appears here and nowhere else.
id*stringUnique identifier of the tenant invite.
tenant_id*stringThe tenant the tenant invite belongs to.
email*stringEmail address.
Example: "alice@example.com"
role_id*stringId of the role.
role_name*stringName of the role.
Example: "member"
status*objectDerived, never stored: revoked > expired > used > pending.
max_uses*numberHow many times the tenant invite can be used, or `null` for no limit.
Example: 1
use_count*numberHow many times the tenant invite has been used.
Example: 0
expires_at*string · date-timeWhen the tenant invite expires (ISO 8601), or `null` if it never does.
revoked_at*string · date-timeWhen the tenant invite was revoked (ISO 8601), or `null` while it is active.
invited_by*stringAccount 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-timeWhen the tenant invite was created (ISO 8601).
code*stringThe 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"
}