Invite a member

POST /fapi/v1/organizations/{org_id}/invitations · called from the environment's sign-in host

Invites an e-mail address to the organization. KeenAuth sends the invitation e-mail; the invitation token and accept link are never returned to you. If a pending invitation already exists for the same address with the same roles, it is sent again and the answer is 200 OK; a new invitation is 201 Created.

Requires the authenticated user's __Host-idp_session cookie with an exact Origin, or a first-party app's front API access token (Authorization: DPoP <token> with a DPoP proof; see Front API access token). The user must be an active member of the organization with the idp_members:invite permission. A user who is not a member gets 404 not_found; a member without the permission gets 403 insufficient_permissions. Only a member who holds the admin role can invite with a privileged role (403 role_not_assignable).

With @keenauth/js: const { invitation, resent } = await keenauth.organizations.invite(orgId, { email, roleIds: [roleId] }).

Request

Headers:

Header Required Description
Idp-Client yes SDK identifier.
Origin yes, with the cookie https://<sign-in host>.

org_id: the organization identifier (org_…).

Body:

Field Required Description
email yes The address to invite, at most 254 characters.
role_ids no At most 10 roles (rol_…); none means the organization's default role.
ttl_days no How long the invitation stays valid, 1–30 days; the environment's default when omitted.

Response

201 Created with Location and ETag, or 200 OK when a pending invitation was sent again. The body is the invitation:

id (inv_…), email (only while pending, else null), role_ids, delivery, delivery_status (queued, sent, bounced or not_sent), status (pending, accepted, revoked or expired), send_count, last_sent_at, expires_at, accepted_user_id, accepted_at, revoked_at, created_at, updated_at, version.

Errors

Status Code When
400 unknown_field The body has a field not listed above.
401 unauthenticated No valid session cookie or token.
403 insufficient_permissions The user lacks idp_members:invite in the organization.
403 role_not_assignable A role is privileged and the user does not hold the admin role.
403 origin_not_allowed The Origin does not match.
404 not_found No such organization or role for this user.
409 invitation_already_pending A pending invitation for this address has different roles.
409 membership_already_exists The address belongs to a member of the organization.
409 organization_membership_limit_reached The organization has reached its member limit.
409 organization_disabled The organization is disabled or pending deletion (organization_pending_deletion).
422 validation_failed email, role_ids or ttl_days is missing or invalid.
429 invite_rate_limited Too many invitations or resends; retry after Retry-After.
501 not_implemented Invitation e-mail is not set up in this environment.
503 service_unavailable Temporarily unavailable; retry after Retry-After.

Example

curl -X POST "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/invitations" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"email":"new.member@example.com","role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],"ttl_days":7}'

{
  "id": "inv_01jbz6x8kq3m2n4p5r6s7t8v9d",
  "email": "new.member@example.com",
  "role_ids": ["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],
  "delivery": "email",
  "delivery_status": "queued",
  "status": "pending",
  "send_count": 1,
  "last_sent_at": "2026-11-03T10:00:00Z",
  "expires_at": "2026-11-10T10:00:00Z",
  "accepted_user_id": null,
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-11-03T10:00:00Z",
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 1
}

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.