# Bağlantı oluşturma

`POST /v1/connections` · izin `connections:write`

Ortamda yeni bir bağlantı kaydeder. Protokol yapılandırması gerektiren bağlantılar (`social`, `enterprise`) `inactive` durumunda başlar; bunları `:activate` ile açıkça etkinleştirin. Bir `enterprise` bağlantısı `active` olarak oluşturulamaz: yeni bir bağlantının henüz başarılı bir test girişi olamaz. Ayarlar gizli bilgi içermemelidir. Bir ortamda en fazla 100 bağlantı ve 20 genel sosyal (`oidc_generic`, `oauth2_generic`) bağlantı bulunabilir; bir kuruluşta ise en fazla 20 bağlantı bulunabilir.

## İstek

JSON gövdesi (bilinmeyen alanlar `400 unknown_field` ile reddedilir):

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `key` | string | evet | Kararlı yapılandırma anahtarı, `^[a-z0-9_-]{1,64}$`, ortamda benzersiz, değiştirilemez. |
| `type` | string | evet | `database`, `passwordless`, `passkey`, `social` veya `enterprise`. Değiştirilemez. |
| `strategy` | string | evet | Tür için strateji, örneğin `password`, `email_otp`, `google`, `saml`. Değiştirilemez. |
| `name` | string | evet | 1-128 karakter, ortamda benzersiz. |
| `display_name` | string | hayır | Giriş ekranlarında gösterilen 1-128 karakter. |
| `status` | string | hayır | `active` veya `inactive`. `database`, `passwordless`, `passkey` için varsayılan `active`, `social`, `enterprise` için varsayılan `inactive`. |
| `org_id` | string | hayır | Sahip kuruluş (`org_…`), yalnızca `enterprise`. Atlanırsa ortam bağlantısı olur. Değiştirilemez. |
| `allowed_email_domains` | array of strings | hayır | Ana bölge keşfiyle bu bağlantıya yönlendirilen e-posta alan adları: IDNA A-etiketi, küçük harf (örneğin `xn--bcher-kva.example`), benzersiz, en fazla 100; yalnızca `enterprise` için boş olmayabilir. Kuruluş bağlantısında her alan adı kuruluşun doğrulanmış bir alan adı olmalıdır ve `active` bir kuruluş bağlantısı en az bir alan adı gerektirir. |
| `allow_external_domains` | boolean | hayır | Listelenmeyen e-posta alan adına sahip kullanıcıların da giriş yapmasına izin verir. Yalnızca `enterprise`; varsayılan `false`. |
| `jit_mode` | string | hayır | Anlık sağlama: `create` kullanıcıyı ilk girişte oluşturur, `create_and_update` profili ayrıca kimlik sağlayıcıdan günceller, `off` mevcut bir hesap gerektirir. Yalnızca `enterprise`. Ortam bağlantısında varsayılan `create_and_update`, kuruluş bağlantısında varsayılan `off`tur. |
| `email_trust` | boolean | hayır | Otomatik hesap bağlama ve anlık sağlama için kimlik sağlayıcının bildirdiği e-posta adresine güven. Yalnızca `enterprise`; varsayılan `false`. Kuruluş bağlantısında `true` için boş olmayan ve her alan adı kuruluşun doğrulanmış alan adı olan bir `allowed_email_domains` gerekir. |
| `default_role_ids` | array of strings | hayır | Anlık girişle oluşturulan üyeliğe, ortamın varsayılan rolüne ve bağlantının grup rol eşlemelerine ek olarak verilecek ortam rolleri (`rol_…`, benzersiz, en fazla 10). Yalnızca kuruluş `enterprise` bağlantısında. Her rol bu ortamın ayrıcalıklı olmayan bir ortam rolü olmalıdır; başka bir ortamın rolü, bir kuruluş rolü, ayrıcalıklı bir rol veya var olmayan bir rol reddedilir. Daha sonra silinen ya da ayrıcalıklı hale getirilen rol giriş sırasında atlanır. |
| `trust_idp_mfa` | boolean | hayır | Kimlik sağlayıcının bildirdiği çok faktörlü kimlik doğrulamayı (SAML kimlik doğrulama bağlamı, OIDC `amr`/`acr`) oturumun MFA kanıtı olarak kabul eder. Yalnızca `enterprise`; varsayılan `false`. |
| `settings` | object | hayır | En fazla 32 KiB, gizli bilgi içermeyen ayarlar. Gizli bilgi gibi görünen anahtarlar veya değerler reddedilir. |
| `Idempotency-Key` | header | hayır | Yeniden denenen isteği güvenli kılan isteğe bağlı anahtar (16-64 karakter). |

## Yanıt

`201 Created` ile bağlantı ve sürümünü tutan bir `ETag` üstbilgisi döner.

```json
{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "inactive",
  "org_id": null,
  "allowed_email_domains": [],
  "allow_external_domains": false,
  "jit_mode": null,
  "email_trust": null,
  "default_role_ids": [],
  "trust_idp_mfa": null,
  "allow_idp_initiated": null,
  "idp_initiated_default_application_id": null,
  "idp_initiated_allowed_application_ids": [],
  "settings": {},
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}
```

## Passkey ayarları

`type: "passkey"` için `settings` nesnesi yalnızca aşağıdaki anahtarları kabul eder. Diğer her anahtar, yanlış bir tür veya aralık dışı bir değer `422 validation_failed` ile reddedilir ve `errors[].pointer` alanında `/settings/max_credentials_per_user` gibi bir yol bildirilir. `null` değeri varsayılanı ifade eder. Biçim hataları plan hatalarından önce bildirilir.

| Anahtar | Tür | Notlar |
|---|---|---|
| `rp_id` | string | Yoksa, `null` veya boşsa: her giriş ana makinesi kendi rpId değerine sahiptir. Aksi halde ortamın `active` özel alan adının ana makine adı (küçük harf, IDNA A-etiketi); başka her değer `422 validation_failed` (`/settings/rp_id`) döner. Ortamda passkey varsa, değiştirmek için [Passkey rpId değerini değiştirme](change-rp-id.md) sayfasını kullanın. |
| `rp_name` | string | En fazla 128 karakter. |
| `passkey_first_factor_enabled`, `security_key_second_factor_enabled` | boolean | Varsayılan `true`. |
| `user_verification` | string | `preferred` (varsayılan) veya `required`. |
| `max_credentials_per_user` | integer | 1-20, varsayılan 20; ondalıklı değerler reddedilir. |
| `require_device_bound_passkeys` | boolean | Plana bağlı: `true` için Startup gerekir. |
| `attestation_required` | boolean | Plana bağlı: `true` için Enterprise gerekir. |
| `aaguid_allowlist`, `aaguid_blocklist` | array of UUID strings | Her biri en fazla 500 benzersiz girdi (hatalar `/settings/<key>/<index>` yolunu gösterir). Plana bağlı: boş olmayan bir liste için Enterprise gerekir. |
| `related_origins` | array of strings | `https://host[:port]` kaynakları. Plana bağlı: boş olmayan bir liste için Enterprise gerekir. |
| `passkey_enrollment_prompt` | string | `off` veya `after_login` (varsayılan). |

Plana bağlı bir anahtara varsayılan olmayan bir değer yazılırsa `403 plan_feature_unavailable` döner ve `feature` ile `required_plan` üyeleri bulunur. Plan yetkileri kullanılabilir olana kadar bu anahtarlar hiçbir ortamda ayarlanamaz; varsayılan bir değer (`false`, `[]`, `null`) yazmak ya da anahtarı kaldırmak her zaman mümkündür. Özellik kullanılabilir olduğunda her `related_origins` girdisi ortamın etkin ve doğrulanmış bir özel alan adı olmalıdır; aksi halde istek `422 related_origin_not_verified` ile başarısız olur.

## Hatalar

| HTTP | kod | Ne zaman |
|---|---|---|
| 400 | `unknown_field` | Gövde bilinmeyen bir alan içerir. |
| 403 | `quota_exceeded` | Ortamın veya kuruluşun (`org_id`) bağlantı sınırına ulaşıldı. |
| 409 | `conflict` | Aynı `key` veya `name` değerine sahip bir bağlantı var. |
| 409 | `connection_test_required` | İstek `status: active` ile bir `enterprise` bağlantısı oluşturur; hiçbir şey yazılmaz. Bağlantıyı `inactive` oluşturun, giriş testini yapın, sonra `:activate` ile etkinleştirin. |
| 415 | `unsupported_media_type` | İçerik türü `application/json` değil. |
| 422 | `validation_failed` | Bir alan eksik veya geçersiz; `errors[].pointer` bunu belirtir (örneğin gizli bilgi gibi ayarlar için `/settings/client_secret`). |
| 422 | `related_origin_not_verified` | İlişkili bir kaynak ortamın doğrulanmış bir özel alan adı değil. |
| 403 | `plan_feature_unavailable` | Planınız belirlediğiniz bir ayarı içermiyor (`feature`, `required_plan` üyeleri), örneğin `attestation_required`. |
| 401 | `unauthenticated` | Kimlik bilgisi eksik, geçersiz veya iptal edilmiş. |
| 403 | `insufficient_permissions` | Kimlik bilgisinin gerekli izni yok. |
| 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

```bash
curl -X POST https://api.eu.keenauth.com/v1/connections \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"google","type":"social","strategy":"google","name":"Google"}'
```