メンバーを招待

POST /fapi/v1/organizations/{org_id}/invitations · 環境のサインインホストから呼び出し

メールアドレスを組織に招待します。招待メールは KeenAuth が送信します。招待トークンと承諾リンクがお客様に返されることはありません。同じアドレスに同じロールの保留中の招待がすでに存在する場合は、再送され、応答は 200 OK になります。新しい招待の場合は 201 Created になります。

認証済みユーザーの __Host-idp_session Cookie と、正確な Origin、または自社アプリのフロントAPIアクセストークン（DPoP 証明付きの Authorization: DPoP <token>。フロントAPIアクセストークン を参照）が必要です。ユーザーはその組織の有効なメンバーであり、idp_members:invite 権限を持っている必要があります。メンバーでないユーザーには 404 not_found を返します。権限のないメンバーには 403 insufficient_permissions を返します。特権ロールで招待できるのは、管理者ロールを持つメンバーのみです（403 role_not_assignable）。

@keenauth/js を使う場合：const { invitation, resent } = await keenauth.organizations.invite(orgId, { email, roleIds: [roleId] })。

リクエスト

ヘッダー：

ヘッダー 必須 説明
Idp-Client はい SDK の識別子。
Origin Cookie 使用時は必須 https://<sign-in host>。

org_id：組織の識別子（org_…）。

ボディ：

フィールド 必須 説明
email はい 招待するメールアドレス。254 文字以内。
role_ids いいえ 最大 10 件のロール（rol_…）。指定しない場合は、組織の既定ロールになります。
ttl_days いいえ 招待の有効期間。1〜30 日。省略時は環境の既定値。

レスポンス

201 Created と Location および ETag が返されます。保留中の招待が再送された場合は 200 OK が返されます。ボディは招待の内容です。

id（inv_…）、email（保留中の間のみ。それ以外は null）、role_ids、delivery、delivery_status（queued、sent、bounced、または not_sent）、status（pending、accepted、revoked、または expired）、send_count、last_sent_at、expires_at、accepted_user_id、accepted_at、revoked_at、created_at、updated_at、version。

エラー

ステータス コード 条件
400 unknown_field 上記にないフィールドがボディに含まれています。
401 unauthenticated 有効なセッション Cookie またはトークンがありません。
403 insufficient_permissions ユーザーにその組織での idp_members:invite 権限がありません。
403 role_not_assignable ロールが特権ロールであり、ユーザーが管理者ロールを持っていません。
403 origin_not_allowed Origin が一致しません。
404 not_found このユーザーに対応する組織またはロールが存在しません。
409 invitation_already_pending このアドレスに対する保留中の招待があり、ロールが異なります。
409 membership_already_exists このアドレスは、組織のメンバーにすでに属しています。
409 organization_membership_limit_reached 組織がメンバー数の上限に達しています。
409 organization_disabled 組織が無効化されているか、削除処理中です（organization_pending_deletion）。
422 validation_failed email、role_ids、または ttl_days が欠けているか、不正です。
429 invite_rate_limited 招待または再送の回数が多すぎます。Retry-After の後に再試行してください。
501 not_implemented この環境では招待メールが設定されていません。
503 service_unavailable 一時的に利用できません。Retry-After の後に再試行してください。

例

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
}

個人データ

このエンドポイントは個人データ（組織のメンバーシップと招待）を扱います。KeenAuth API における個人データ では、保存される内容、保存期間、削除方法について説明しています。どのフィールドにも、特別な種類の個人データ（健康、生体情報、宗教、政治的意見、性的指向）を送信しないでください。