# メンバーを招待

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

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

認証済みユーザーの `__Host-idp_session` Cookie と、正確な `Origin`、または自社アプリのフロントAPIアクセストークン（DPoP 証明付きの `Authorization: DPoP <token>`。[フロントAPIアクセストークン](/docs/api/fapi/front-api-token) を参照）が必要です。ユーザーはその組織の有効なメンバーであり、`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` の後に再試行してください。 |

## 例

```bash
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}'
```

```json
{
  "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 における個人データ](/docs/policies/personal-data) では、保存される内容、保存期間、削除方法について説明しています。どのフィールドにも、特別な種類の個人データ（健康、生体情報、宗教、政治的意見、性的指向）を送信しないでください。