Authentication

Invitations

3 min read·Updated May 7, 2026

The Invitations card under Application → Authentication lets you (or your customers' admins) onboard users by email. The user clicks the link, sets up their account, and lands inside the application with whatever roles you pre-assigned.

curl -X POST https://your-app.authaz.io/api/v1/invitations \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newhire@yourcompany.com",
    "roleIds": ["role_member"],
    "metadata": { "department": "Engineering" }
  }'

{
  "id": "inv_01h...",
  "email": "newhire@yourcompany.com",
  "status": "pending",
  "expiresAt": "2026-05-13T15:30:00Z",
  "invitedBy": "user_01h..."
}

Previous: Signup
Next: Password Authentication

# Single invitation
curl -X POST https://your-app.authaz.io/api/v1/invitations \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newhire@yourcompany.com",
    "roleIds": ["role_member"],
    "expiresInDays": 7
  }'

curl -X POST https://your-app.authaz.io/api/v1/applications/{appId}/tenants/{tenantId}/invitations \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newhire@yourcompany.com",
    "roleIds": ["role_member"]
  }'

Setting	What it controls
Enabled	Master switch. Disable to prevent any new invitations from being sent (existing pending ones still work).
Default expiration	How long an invitation link remains usable. Default 7 days.
Allow re-invitation	If `true`, you can invite the same email again before the previous one expires (creates a fresh code).
Email template	The Authaz Sign-In template used. Customize copy, branding, CTA text. See Communications.

# List all
curl https://your-app.authaz.io/api/v1/invitations \
  -H "X-API-Key: $AUTHAZ_API_KEY"
 
# Filter by status
curl 'https://your-app.authaz.io/api/v1/invitations?status=pending' \
  -H "X-API-Key: $AUTHAZ_API_KEY"
 
# Pending count for the dashboard badge
curl https://your-app.authaz.io/api/v1/invitations/pending-count \
  -H "X-API-Key: $AUTHAZ_API_KEY"

Status	Meaning
`pending`	Email sent, waiting for the user to click the link.
`accepted`	User completed signup. The user record now exists.
`expired`	The link expired before the user used it.
`revoked`	An admin canceled the invitation before it was used.

# Resend (regenerates the code, restarts the expiration clock)
curl -X POST https://your-app.authaz.io/api/v1/invitations/{invitationId}/resend \
  -H "X-API-Key: $AUTHAZ_API_KEY"
 
# Revoke
curl -X DELETE https://your-app.authaz.io/api/v1/invitations/{invitationId} \
  -H "X-API-Key: $AUTHAZ_API_KEY"

const invitations = [
  { email: "alice@acme.com", roleIds: ["role_admin"] },
  { email: "bob@acme.com",   roleIds: ["role_member"] },
  { email: "carol@acme.com", roleIds: ["role_member"] },
];
 
await Promise.all(invitations.map((inv) =>
  fetch("https://your-app.authaz.io/api/v1/invitations", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.AUTHAZ_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(inv),
  })
));

Invitations

Where it lives#

Sending invitations#

From the dashboard#

From the API#

Tenant-scoped invitations#

Configuration#

Listing invitations#

Resending and revoking#

What happens when the user clicks#

Customizing the email#

Bulk invitations#

Next steps#