Bir kişiyi kuruluşa davet edin

POST /v1/invitations · izin invitations:write

Bir e-posta adresinin kuruluşa katılması için davet oluşturur. organization_id belirtilmezse davet bir ortam davetidir: davetle yalnızca davetle hesap oluşturma modu için kayıt bağlantısı olur, üyelik açmaz ve rol taşıyamaz (role_ids gönderilirse 422 validation_failed döner). Yanıtta organization_id: null bulunur. delivery zorunludur: email değeri, davet e-postasını ortamın davet şablonuyla gönderir (delivery_status: queued); bağlantı yalnızca e-postada bulunur ve yanıtta accept_url yer almaz. link_only değeri e-posta göndermez ve paylaşmanız için bağlantıyı döndürür. Kabul bağlantısı (accept_url) yalnızca bu yanıtta, bir kez döndürülür; hiçbir uç nokta bunu daha sonra döndürmez. Yanıt Cache-Control: no-store başlığını taşır ve aynı Idempotency-Key için yeniden oynatılan bir yanıt bağlantıyı içermez ve secret_redacted: true bilgisini taşır. Dağıtım için davet e-postası yapılandırılmamışsa (yalnızca üretim dışı kurulumlarda), email teslimi 501 not_implemented döner ve hiçbir kayıt yazılmaz. Kuruluş ve e-posta için aynı rollerle bekleyen bir davet zaten varsa, yeni bağlantıyla yeniden gönderilir ve yanıt 200 olur. Süresi dolmuş ama henüz işlenmemiş bekleyen bir davet aynı istekte expired olarak işaretlenir ve yeni bir davet yazılır (invitation.expired olarak denetlenir). Aynı rollerle bekleyen bir email daveti e-postayla yeniden gönderilir: yanıt 200 olur, delivery: email içerir ve accept_url içermez. Yazma işlemi invitation.created olarak denetlenir.

İstek

Alan Tür Zorunlu Açıklama
organization_id string hayır Kuruluş kimliği (org_…); ortam daveti için bu alanı atlayın (rol yok).
email string evet Davetlinin e-posta adresi, en fazla 320 karakter.
delivery string evet email (bağlantı yalnızca e-postada) veya link_only (bağlantı yalnızca bu yanıtta).
role_ids string[] hayır Kabulde verilen roller (rol_…), en fazla 10; boşsa varsayılan üye rolü.
application_id string hayır Davetlinin açacağı uygulama (app_…); bu ortamda var olmalıdır.
ttl_days integer hayır 1–30; varsayılan, ortamın invitation_ttl_days değeridir (7).

Yanıt

Davet ve kabul bağlantısıyla birlikte 201 Created (bekleyen bir davet yeniden gönderildiyse 200 OK).

{
  "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>"
}

Hatalar

HTTP kod Ne zaman
404 not_found Kuruluş veya uygulama bu ortamda yok.
409 invitation_already_pending Bu e-posta için farklı rollerle bekleyen bir davet var.
409 membership_already_exists E-posta adresi zaten bir üyeye ait.
409 organization_disabled Kuruluş devre dışı.
422 invitation_invalid Davet bu değerlerle oluşturulamaz.
422 validation_failed Bir alan eksik veya geçersiz.
429 invite_rate_limited Davet 10 dakikadan kısa süre önce veya zaten 5 kez yeniden gönderildi.
501 not_implemented delivery değeri email ve dağıtım için davet e-postası yapılandırılmamış.
401 unauthenticated Kimlik bilgisi eksik, geçersiz veya iptal edilmiş.
403 insufficient_permissions Kimlik bilgisinde gerekli izin yok. Ayrıcalıklı (is_privileged) bir rol atamak ayrıca roles:write gerektirir; bu izin yoksa hiçbir kayıt yazılmaz ve required_permissions her iki izni de listeler.
429 rate_limited Hız sınırı aşıldı; Retry-After süresinden sonra yeniden deneyin.
503 service_unavailable Bir bağımlılık geçici olarak kullanılamıyor; Retry-After süresinden sonra yeniden deneyin.

Örnek

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"]}'

Kişisel veriler

Bu uç nokta kişisel veri içerir: kuruluş üyelikleri ve davetler. KeenAuth API'lerinde kişisel veriler 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.