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

```json
{
  "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](change-rp-id.md). |
| `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](change-rp-id.md). 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

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