# Kuruluş politikasını önizleyin

`POST /v1/organizations/{org_id}/policies/{policy_kind}:preview` · İzin `organizations:write`

Aday bir ayarlar nesnesini kaydetmeden değerlendirir. Gövde, [politika oluşturma veya değiştirme](/docs/api/management/organization-policies/put) ile aynıdır; sunucu bunu aynı kurallarla ve aynı plan kapısıyla denetler. Bu nedenle `PUT` reddedecek bir aday, burada aynı sorun koduyla reddedilir. Hiçbir şey yazılmaz: politika, denetim kaydı ve olay oluşturulmaz. İstek `If-Match` ve `Idempotency-Key` almaz, yanıt ise `ETag` içermez.

Yanıt, engellenecek kullanıcıları değil, adayın uygulandığı kullanıcıları sayar (`basis` `users_in_scope`); bir istisna dışında: `phishing_resistant` (aşağıya bakın). Yalnızca oturum açma sırasında bilinen veya politika hizmetinin tutmadığı koşullar filtrelenmez; `not_evaluated` bunları listeler, böylece sayı olduğundan fazla gibi okunmaz.

| Tür | Sayılan kullanıcılar | `not_evaluated` |
|---|---|---|
| `authentication_methods` | Kuruluşun etkin üyeleri | `credentials` |
| `mfa` (`required_for` `admins` veya `all`) | Kuruluşun etkin üyeleri | `mfa_enrollment`; ayrıca `admin_scope` için `admins` |
| `phishing_resistant` (`required_for` `admins` veya `all`) | Kabul edilmiş bir WebAuthn kimlik bilgisi olmayan kuruluşun etkin üyeleri (`basis` `users_without_webauthn`, aşağıya bakın) | `credential_policy`; ayrıca `admin_scope` için `admins` |
| `sso_enforcement` `org_context` | Kuruluşun etkin üyeleri, eksi `bypass_user_ids` | `federated_sign_in` |
| `sso_enforcement` `verified_domains` | Etkin üyeler, artı bu kuruluşun doğrulanmış bir alan adındaki e-posta adresine sahip ortamın etkin kullanıcıları, eksi `bypass_user_ids` | `federated_sign_in` |
| `session` | Kuruluşun etkin üyeleri | yok |
| `ip_allowlist` | Kuruluşun etkin üyeleri | `client_ip`; ayrıca `admin_scope` için `admins` |

`phishing_resistant` için sayı ve örnek, bugün phishing'e dayanıklı biçimde oturum açamayan kapsamdaki kullanıcılardır: AAGUID izin listesinin kabul ettiği, etkin bir WebAuthn kimlik bilgisi (bir passkey veya birinci faktörle kullanılan bir güvenlik anahtarı) olmayan kullanıcılar. İzin listesi adayınkidir; adayınki boşsa ortamınkidir. Bir izin listesi varsa, bir kimlik bilgisi yalnızca modeli listelenmişse ve onayı doğrulanmışsa sayılır. Beklemedeki, iptal edilmiş ve klonlanmış şüphesi olan kimlik bilgileri sayılmaz. `credential_policy`, ortamın onaylama gereksiniminin, cihaza bağlı passkey kuralının ve kimlik doğrulayıcı model durumunun uygulanmadığı anlamına gelir; bu nedenle sayı, engellenecek kullanıcı sayısından düşük olabilir. Kapsamda 10.000'den fazla kullanıcı olduğunda yanıt `users_in_scope` moduna geçer ve `passkey_enrollment` döner. Kimlik bilgisi verileri okunamazsa istek `503` ile başarısız olur ve sayı döndürülmez.

`required_for` `none` ve `mode` `off` hiçbir kullanıcıyı saymaz. Etkin üye, üyeliği etkin ve kullanıcısı engellenmemiş olan üyedir; her kullanıcı bir kez sayılır. `admin_scope`, `admins` değerinin tüm üyeler olarak sayıldığı anlamına gelir; oturum açma bugün bunu böyle uygular. Başka bir kuruluşun veya başka bir ortamın kullanıcıları hiçbir zaman sayılmaz.

## İstek

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `org_id` | yol | evet | Kuruluş kimliği (`org_…`). |
| `policy_kind` | yol | evet | Politika türü: `authentication_methods`, `mfa`, `phishing_resistant`, `sso_enforcement`, `session` veya `ip_allowlist`. Başka bir değer `404` döndürür. |
| `settings` | nesne | evet | Türün aday ayarlar nesnesi; `PUT` ile aynı alanlara sahiptir. |

İstek gövdesi:

```json
{
  "settings": {
    "required_for": "all",
    "allowed_factors": [
      "totp",
      "webauthn"
    ],
    "enrollment_grace_days": 7
  }
}
```

## Yanıt

`200 OK`. `sample`, sayılan kümedeki en fazla 20 kullanıcıyı, yalnızca kullanıcı kimliğiyle ve kimliğe göre sıralı olarak içerir.

| Alan | Tür | Açıklama |
|---|---|---|
| `organization_id` | string | Kuruluş kimliği (`org_…`). |
| `policy_kind` | string | Önizlenen tür. |
| `basis` | string | `affected_count` neyi sayar: `users_in_scope` veya `phishing_resistant` için `users_without_webauthn`. Yeni değerler eklenebilir. |
| `affected_count` | integer | `basis` tarafından sayılan kullanıcı sayısı. |
| `sample` | array | `user_id` alanlı en fazla 20 nesne (`usr_…`). |
| `not_evaluated` | array | Sayının filtrelemediği koşullar: `admin_scope`, `credentials`, `mfa_enrollment`, `passkey_enrollment`, `federated_sign_in`, `client_ip`, `credential_policy`. Yeni değerler eklenebilir. |

```json
{
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "policy_kind": "mfa",
  "basis": "users_in_scope",
  "affected_count": 2,
  "sample": [
    {
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4b"
    },
    {
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c"
    }
  ],
  "not_evaluated": [
    "mfa_enrollment"
  ]
}
```

## Hatalar

| HTTP | code | Ne zaman |
|---|---|---|
| 400 | `unknown_field` | Gövdede şemada olmayan bir alan var. |
| 403 | `plan_feature_unavailable` | Tür veya AAGUID izin listesi daha yüksek bir plan gerektirir; sorun `feature` ve `required_plan` bilgilerini içerir. |
| 404 | `not_found` | Kuruluş yok veya tür bilinmiyor. |
| 409 | `domain_not_verified` | `sso_enforcement` ile `mode` `verified_domains` kuruluşta doğrulanmış bir alan adı gerektirir. |
| 409 | `connection_test_required` | `sso_enforcement` etkinleştirmek (`off` veya hiç politika olmadan), `connection_ids` arasından en az birinin son 24 saat içindeki geçerli yapılandırmasıyla başarılı bir test oturum açması gerektirir. Bir bağlantı testi (`POST /v1/connections/{connection_id}:test`) çalıştırın ve yeniden deneyin. |
| 409 | `organization_pending_deletion` | Kuruluş, self-servis silme işlemini bekliyor. |
| 422 | `validation_failed` | Bir ayar alanı bilinmiyor veya geçersiz; `errors[]`, `/settings/…` öğesini gösterir. |
| 422 | `policy_weaker_than_parent` | Ayar, ortamın ayarından daha zayıf; `errors[]` zayıf alanı gösterir. |
| 422 | `at_least_one_method` | `authentication_methods` hiçbir oturum açma yöntemi bırakmıyor. |
| 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 (`phishing_resistant` için, kimlik bilgisi verileri okunamadığında da); `Retry-After` süresinden sonra yeniden deneyin. |

## Örnek

```bash
curl -X POST https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/policies/mfa:preview \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"required_for":"all","allowed_factors":["totp","webauthn"]}}'
```

```bash
keenauth organizations policies preview org_01j9xk3m7q8r2s4t6v8w0y2z4a mfa \
  --data '{"settings":{"required_for":"all","allowed_factors":["totp","webauthn"]}}'
```