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). 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

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
}

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.