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.

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

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"}'