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

```json
{
  "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

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

```bash
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:

```json
{
  "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`.