# Bir üye davet edin

`POST /fapi/v1/organizations/{org_id}/invitations` · ortamın oturum açma sunucusundan çağrılır

Kuruluşa bir e-posta adresi davet eder. Davet e-postasını KeenAuth gönderir; davet belirteci ve kabul bağlantısı size hiçbir zaman döndürülmez. Aynı adres ve aynı rollerle bekleyen bir davet zaten varsa, yeniden gönderilir ve yanıt `200 OK` olur; yeni bir davet ise `201 Created` döner.

Kullanıcının `__Host-idp_session` çerezi ve tam eşleşen bir `Origin` gereklidir; ya da birinci taraf bir uygulamanın ön yüz API erişim belirteci (`Authorization: DPoP <token>` ve bir DPoP kanıtıyla; bkz. [Ön yüz API erişim belirteci](/docs/api/fapi/front-api-token)). Kullanıcı kuruluşun aktif bir üyesi olmalı ve `idp_members:invite` iznine sahip olmalıdır. Üye olmayan bir kullanıcı `404 not_found` alır; izni olmayan bir üye ise `403 insufficient_permissions` alır. Yalnızca yönetici rolüne sahip bir üye, ayrıcalıklı bir rolle davet edebilir (`403 role_not_assignable`).

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

## İstek

Başlıklar:

| Başlık | Zorunlu | Açıklama |
| --- | --- | --- |
| `Idp-Client` | evet | SDK tanımlayıcısı. |
| `Origin` | çerezle birlikte evet | `https://<sign-in host>`. |

`org_id`: kuruluş tanımlayıcısı (`org_…`).

Gövde:

| Alan | Zorunlu | Açıklama |
| --- | --- | --- |
| `email` | evet | Davet edilecek adres, en fazla 254 karakter. |
| `role_ids` | hayır | En fazla 10 rol (`rol_…`); belirtilmezse kuruluşun varsayılan rolü kullanılır. |
| `ttl_days` | hayır | Davetin ne kadar geçerli kalacağı, 1–30 gün; belirtilmezse ortamın varsayılanı. |

## Yanıt

`Location` ve `ETag` ile birlikte `201 Created`; ya da bekleyen bir davet yeniden gönderildiğinde `200 OK`. Gövde davetin kendisidir:

`id` (`inv_…`), `email` (yalnızca beklemedeyken, aksi halde `null`), `role_ids`, `delivery`, `delivery_status` (`queued`, `sent`, `bounced` veya `not_sent`), `status` (`pending`, `accepted`, `revoked` veya `expired`), `send_count`, `last_sent_at`, `expires_at`, `accepted_user_id`, `accepted_at`, `revoked_at`, `created_at`, `updated_at`, `version`.

## Hatalar

| Durum | Kod | Ne zaman |
| --- | --- | --- |
| 400 | `unknown_field` | Gövdede yukarıda listelenmeyen bir alan varsa. |
| 401 | `unauthenticated` | Geçerli bir oturum çerezi veya belirteci yoksa. |
| 403 | `insufficient_permissions` | Kullanıcının kuruluşta `idp_members:invite` izni yoksa. |
| 403 | `role_not_assignable` | Bir rol ayrıcalıklıysa ve kullanıcı yönetici rolüne sahip değilse. |
| 403 | `origin_not_allowed` | `Origin` eşleşmiyorsa. |
| 404 | `not_found` | Bu kullanıcı için böyle bir kuruluş veya rol yoksa. |
| 409 | `invitation_already_pending` | Bu adres için farklı rollerle bekleyen bir davet varsa. |
| 409 | `membership_already_exists` | Adres kuruluşun bir üyesine aitse. |
| 409 | `organization_membership_limit_reached` | Kuruluş üye sınırına ulaştıysa. |
| 409 | `organization_disabled` | Kuruluş devre dışıysa veya silinmeyi bekliyorsa (`organization_pending_deletion`). |
| 422 | `validation_failed` | `email`, `role_ids` veya `ttl_days` eksik veya geçersizse. |
| 429 | `invite_rate_limited` | Çok fazla davet veya yeniden gönderme varsa; `Retry-After` sonrası yeniden deneyin. |
| 501 | `not_implemented` | Bu ortamda davet e-postası ayarlanmamışsa. |
| 503 | `service_unavailable` | Geçici olarak kullanılamıyorsa; `Retry-After` sonrası yeniden deneyin. |

## Örnek

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

## Kişisel veriler

Bu uç nokta kişisel veri içerir: kuruluş üyelikleri ve davetler. [KeenAuth API'lerinde kişisel veriler](/docs/policies/personal-data), neyin saklandığını, ne kadar süre tutulduğunu ve nasıl silindiğini açıklar. Hiçbir alanda özel nitelikli kişisel verileri (sağlık, biyometrik veriler, din, siyasi görüşler, cinsel yönelim) göndermeyin.