Invite a person to an organization

POST /v1/invitations · permission invitations:write

Creates an invitation for an e-mail address to join the organization. Without organization_id the invitation is an environment invitation: it is the sign-up link for the invite-only sign-up mode, opens no membership and cannot carry roles (role_ids returns 422 validation_failed), and the response has organization_id: null. delivery is required: email sends the invitation e-mail with the environment's invitation template (delivery_status: queued), the link is only in the e-mail and the response has no accept_url; link_only sends no e-mail and returns the link for you to share. The accept link (accept_url) is returned only in this response, once; no endpoint returns it later. The response carries Cache-Control: no-store, and a response replayed for the same Idempotency-Key omits the link and carries secret_redacted: true. If invitation e-mail is not configured for the deployment (non-production setups only), email delivery returns 501 not_implemented and nothing is written. If a pending invitation with the same roles already exists for the organization and e-mail, it is resent with a new link and the response is 200. A pending invitation that has expired but not yet been processed is marked expired in the same request and a new invitation is written (audited as invitation.expired). A pending email invitation with the same roles is resent by e-mail: the response is 200 with delivery: email and no accept_url. The write is audited as invitation.created.

Request

Field Type Required Description
organization_id string no Organization ID (org_…); omit it for an environment invitation (no roles).
email string yes E-mail address of the invitee, up to 320 characters.
delivery string yes email (link only in the e-mail) or link_only (link only in this response).
role_ids string[] no Roles granted on acceptance (rol_…), at most 10; default member role when empty.
application_id string no Application the invitee lands in (app_…); it must exist in this environment.
ttl_days integer no 1–30; default is the environment's invitation_ttl_days (7).

Response

201 Created with the invitation and its accept link (200 OK when a pending invitation was resent).

{
  "id": "inv_01j9xt9v3w4y8z0a2b4c6d8e0g",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "email": "ada@example.com",
  "role_ids": [
    "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
  ],
  "application_id": null,
  "delivery": "link_only",
  "delivery_status": "not_sent",
  "status": "pending",
  "send_count": 1,
  "last_sent_at": "2026-10-12T09:31:00.123456Z",
  "expires_at": "2026-10-19T09:31:00.123456Z",
  "accepted_user_id": null,
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 1,
  "accept_url": "https://acme.eu.keenauth.app/u/login?invitation=<token>"
}

Errors

HTTP code When
404 not_found The organization or the application does not exist in this environment.
409 invitation_already_pending A pending invitation with different roles exists for this e-mail.
409 membership_already_exists The e-mail already belongs to a member.
409 organization_disabled The organization is disabled.
422 invitation_invalid The invitation cannot be created with these values.
422 validation_failed A field is missing or invalid.
429 invite_rate_limited The invitation was resent less than 10 minutes ago or 5 times already.
501 not_implemented delivery is email and invitation e-mail is not configured for the deployment.
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission. Assigning a privileged (is_privileged) role also requires roles:write; without it nothing is written and required_permissions lists both permissions.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable A dependency is temporarily unavailable; retry after the Retry-After period.

Example

curl -i -X POST "https://api.eu.keenauth.com/v1/invitations" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","email":"ada@example.com","delivery":"link_only","role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e"]}'

Personal data

This endpoint carries personal data: organization memberships and invitations. Personal data in the KeenAuth APIs describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.