Mettre à jour une connexion

PATCH /v1/connections/{connection_id} · autorisation connections:write

Met à jour une connexion avec un merge patch JSON (application/merge-patch+json, RFC 7396). If-Match est obligatoire. key, type, strategy et org_id ne peuvent pas être modifiés. Un patch qui ne change rien n'écrit rien et conserve la version. Les paramètres ne doivent pas contenir de secrets.

Requête

Champ Type Obligatoire Description
connection_id string oui Identifiant de la connexion (conn_…).
If-Match header oui L'ETag de la connexion telle que lue en dernier. Absent : 428 ; obsolète : 412.
key string non Ne peut pas être modifié ; la même valeur est acceptée.
type string non Ne peut pas être modifié.
strategy string non Ne peut pas être modifié.
name string non 1 à 128 caractères.
display_name string | null non null le supprime.
status string non active ou inactive.
org_id string | null non Ne peut pas être modifié ; la même valeur est acceptée.
allowed_email_domains array of strings | null non Remplace la liste ; null ou [] la vide. Mêmes règles qu'à la création ; pour une connexion d'organisation, seuls les domaines nouvellement ajoutés sont vérifiés par rapport aux domaines vérifiés de l'organisation.
allow_external_domains boolean non enterprise uniquement.
jit_mode string non create, create_and_update ou off. enterprise uniquement.
email_trust boolean non enterprise uniquement. L'activer pour une connexion d'organisation nécessite un allowed_email_domains non vide dans lequel chaque domaine est un domaine vérifié de l'organisation.
default_role_ids array of strings | null non Remplace la liste ; null ou [] la vide. Mêmes règles qu'à la création ; seuls les rôles nouvellement ajoutés sont vérifiés, donc un rôle déjà présent dans la liste et supprimé plus tard ne bloque pas la mise à jour (il est ignoré à la connexion).
trust_idp_mfa boolean non enterprise uniquement.
settings object | null non Fusionné récursivement (RFC 7396) ; un membre null supprime cette clé ; null efface tous les paramètres. Aucun secret.

Réponse

200 OK avec la connexion mise à jour et le nouvel ETag.

{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "active",
  "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"
}

Paramètres des clés d'accès

Pour type: "passkey", l'objet settings n'accepte que les clés ci-dessous. Toute autre clé, un type incorrect ou une valeur hors plage est rejeté avec 422 validation_failed et un errors[].pointer tel que /settings/max_credentials_per_user. Une valeur null signifie la valeur par défaut. Les erreurs de forme sont signalées avant les erreurs de plan.

Clé Type Remarques
rp_id string Absent, null ou vide : chaque hôte de connexion est son propre rpId. Sinon, le nom d'hôte d'un domaine personnalisé active de l'environnement (minuscules, A-label IDNA) ; toute autre valeur donne 422 validation_failed (/settings/rp_id). Une fois que l'environnement possède des clés d'accès, modifiez-le avec Modifier le rpId des clés d'accès.
rp_name string Jusqu'à 128 caractères.
passkey_first_factor_enabled, security_key_second_factor_enabled boolean Par défaut true.
user_verification string preferred (par défaut) ou required.
max_credentials_per_user integer 1 à 20, par défaut 20 ; les fractions sont rejetées.
require_device_bound_passkeys boolean Réservé à certains plans : true nécessite Startup.
attestation_required boolean Réservé à certains plans : true nécessite Enterprise.
aaguid_allowlist, aaguid_blocklist array of UUID strings 500 entrées uniques au maximum chacune (les erreurs pointent vers /settings/<key>/<index>). Réservé à certains plans : une liste non vide nécessite Enterprise.
related_origins array of strings Origines https://host[:port]. Réservé à certains plans : une liste non vide nécessite Enterprise.
passkey_enrollment_prompt string off ou after_login (par défaut).

Écrire une valeur non par défaut d'une clé réservée à certains plans échoue avec 403 plan_feature_unavailable et les membres feature et required_plan. Tant que les droits du plan ne sont pas disponibles, ces clés ne peuvent être définies dans aucun environnement ; écrire une valeur par défaut (false, [], null) ou supprimer la clé est toujours autorisé. Lorsque la fonctionnalité est disponible, chaque entrée de related_origins doit être un domaine personnalisé vérifié et actif de l'environnement, sinon la requête échoue avec 422 related_origin_not_verified. Les paramètres sont validés après application du merge patch, uniquement lorsque settings fait partie du patch.

Erreurs

HTTP code Quand
400 unknown_field Le patch contient un champ inconnu ou en lecture seule.
404 not_found La connexion n'existe pas ou appartient à un autre environnement.
409 connection_test_required Le patch passe une connexion enterprise à active, ou ajoute un domaine à allowed_email_domains d'une connexion active, sans test réussi de la configuration résultante au cours des 24 dernières heures (voir Activer une connexion) ; rien n'est écrit. La suppression de domaines n'est pas vérifiée.
409 rp_id_change_requires_migration Le patch modifie settings.rp_id d'une connexion par clé d'accès alors que l'environnement possède des clés d'accès qui cesseraient de fonctionner ; utilisez Modifier le rpId des clés d'accès. Rien n'est écrit.
412 precondition_failed If-Match ne correspond pas à la version actuelle.
415 unsupported_media_type Le type de contenu n'est pas application/merge-patch+json.
422 validation_failed Une valeur est invalide ou un champ immuable a été modifié (code: immutable).
422 related_origin_not_verified Une origine liée n'est pas un domaine personnalisé vérifié de l'environnement.
403 plan_feature_unavailable Le plan ne comprend pas un paramètre que vous avez défini (membres feature, required_plan), par exemple attestation_required.
428 precondition_required L'en-tête If-Match est absent.
401 unauthenticated L'identifiant est absent, invalide ou révoqué.
403 insufficient_permissions L'identifiant ne dispose pas de l'autorisation requise.
429 rate_limited La limite de débit a été dépassée ; réessayez après la période indiquée par Retry-After.
503 service_unavailable Une dépendance est temporairement indisponible (par exemple, la vérification des clés d'accès pour une modification de rp_id n'a pas pu s'exécuter, donc rien n'est écrit) ; réessayez après la période indiquée par Retry-After.

Exemple

curl -X PATCH https://api.eu.keenauth.com/v1/connections/conn_0k3v8m1q2x9dz4h7s5t6w0y1ab \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"display_name":"Sign in with Google"}'