Yönetici Portalı bağlantısı oluşturun

POST /v1/admin-portal-links · izin admin-portal-links:write

Müşteri kuruluşlarınızdan birinin BT yöneticisinin, destek ekibinizin yardımına ihtiyaç duymadan barındırılan Yönetici Portalı'nda SSO, dizin senkronizasyonu, alan adı doğrulama ve daha fazlasını ayarlamasına olanak tanıyan bir bağlantı oluşturur. Yöneticiniz uygulamanızda "SSO'yu ayarla" düğmesine her tıkladığında yeni bir bağlantı oluşturun ve onu hemen url adresine yönlendirin: bağlantı 5 dakika geçerlidir ve bir portal oturumunu yalnızca bir kez açar. url yalnızca bu yanıtta, bir kez döndürülür; hiçbir uç nokta onu daha sonra döndürmez. Yanıt Cache-Control: no-store başlığını içerir; aynı Idempotency-Key için yeniden oynatılan bir yanıt url alanını içermez ve secret_redacted: true döndürür. Portal oturumu 60 dakika boşta kalma süresine ve en fazla 8 saat geçerliliğe sahiptir; DELETE /v1/admin-portal-links/{link_id} ile iptal edin. Oluşturma işlemi admin_portal_link.created olarak denetlenir (URL denetim günlüğüne asla girmez).

audit_logs için Business planı, log_streams için Enterprise planı gerekir; diğer amaçlar tüm planlarda kullanılabilir. delivery: email bunun yerine bir davet gönderir: 7 gün geçerlidir ve recipient_email adresine e-posta ile iletilir; yanıtta url ve adres bulunmaz. Alıcı daveti açtığında aynı adrese 6 haneli bir kod (10 dakika geçerli) gönderilir ve yalnızca doğrulanmış kod portal oturumunu açar. Davet e-postası gönderilemezse çağrı 503 service_unavailable ile yanıt verir, Retry-After döndürür ve hiçbir şey oluşturmaz. Bir daveti DELETE /v1/admin-portal-links/{link_id} ile iptal edin. Alıcı adresi hiçbir yanıtta, listede, denetim günlüğünde veya günlükte görünmez.

İstek

Alan Tür Zorunlu Açıklama
organization_id string evet Kuruluş kimliği (org_…); bu ortamda var olmalıdır.
intents string[] evet sso, dsync, domain_verification, certificate_renewal, audit_logs (Business), log_streams (Enterprise) değerlerinden 1–6 tanesi; hiçbiri iki kez kullanılmaz.
return_url string evet En fazla 2048 bayt, kullanıcı bilgisi veya fragment içermeyen mutlak https URL'si. Kaynağı, bu ortamda kayıtlı etkin bir uygulamanın redirect_uri değerinin kaynağı olmalıdır.
delivery string hayır link (varsayılan; yanıtta 5 dakikalık tek kullanımlık url) veya email (recipient_email adresine e-postayla gönderilen 7 günlük davet; url yok).
recipient_email string hayır Yalnızca delivery: email ile kullanılır ve orada zorunludur; en fazla 320 karakter. Eksikse: 422 /recipient_email required; delivery: link ile: not_allowed; geçerli bir adres değilse: invalid_value.

Yanıt

201 Created ile bağlantı ve tek kullanımlık url döner.

{
  "id": "apl_01j9xv2c4d6e8f0g2h4j6k8m0n",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "intents": [
    "dsync",
    "sso"
  ],
  "delivery": "link",
  "return_url": "https://app.example.com/settings/sso",
  "expires_at": "2026-10-12T09:36:00.123456Z",
  "consumed_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "url": "https://acme.eu.keenauth.app/portal/l/<token>"
}

Hatalar

HTTP code Ne zaman
403 plan_feature_unavailable Bir amaç daha üst bir plan gerektiriyorsa; feature ve required_plan bunu belirtir.
404 not_found Kuruluş bu ortamda mevcut değil.
409 organization_disabled Kuruluş etkin değil (devre dışı); bağlantı oluşturulmaz.
409 organization_pending_deletion Kuruluş silinmek üzere planlanmış; bağlantı oluşturulmaz.
422 validation_failed Bir alan eksik veya geçersiz; kaynağı kayıtlı bir uygulama kaynağı değilse /return_url origin_not_registered; /recipient_email required, not_allowed veya invalid_value.
401 unauthenticated Kimlik bilgisi eksik, geçersiz veya iptal edilmiş.
403 insufficient_permissions Kimlik bilgisi gerekli izne sahip değil.
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 veya (delivery: email) davet e-postası gönderilemiyor; hiçbir şey oluşturulmaz. Retry-After süresinden sonra yeniden deneyin.

Örnek

curl -i -X POST "https://api.eu.keenauth.com/v1/admin-portal-links" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","intents":["sso","dsync"],"return_url":"https://app.example.com/settings/sso"}'

E-posta ile davet gönderin

curl -i -X POST "https://api.eu.keenauth.com/v1/admin-portal-links" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","intents":["sso"],"return_url":"https://app.example.com/settings/sso","delivery":"email","recipient_email":"it@customer.example"}'

201 Created; yanıtta url ve adres yoktur:

{
  "id": "apl_01j9xv2c4d6e8f0g2h4j6k8m0n",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "intents": [
    "sso"
  ],
  "delivery": "email",
  "return_url": "https://app.example.com/settings/sso",
  "expires_at": "2026-10-19T09:31:00.123456Z",
  "consumed_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z"
}

CLI ile: keenauth admin-portal-links create --organization-id org_01j9xk3m7q8r2s4t6v8w0y2z4a --intents sso --return-url https://app.example.com/settings/sso --delivery email --recipient-email it@customer.example.