Actualizar una conexión

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

Actualiza una conexión mediante un merge patch de JSON (application/merge-patch+json, RFC 7396). If-Match es obligatorio. key, type, strategy y org_id no se pueden cambiar. Un patch que no cambia nada no escribe nada y conserva la versión. La configuración no debe contener secretos.

Solicitud

Campo Tipo Obligatorio Descripción
connection_id string sí Identificador de la conexión (conn_…).
If-Match header sí El ETag de la conexión tal como se leyó por última vez. Si falta: 428; si está obsoleto: 412.
key string no No se puede cambiar; se acepta el mismo valor.
type string no No se puede cambiar.
strategy string no No se puede cambiar.
name string no De 1 a 128 caracteres.
display_name string | null no null lo borra.
status string no active o inactive.
org_id string | null no No se puede cambiar; se acepta el mismo valor.
allowed_email_domains array of strings | null no Reemplaza la lista; null o [] la borra. Las mismas reglas que al crear; en una conexión de organización solo se comprueban los dominios recién añadidos frente a los dominios verificados de la organización.
allow_external_domains boolean no Solo enterprise.
jit_mode string no create, create_and_update u off. Solo enterprise.
email_trust boolean no Solo enterprise. Activarlo en una conexión de organización requiere un allowed_email_domains no vacío en el que todos los dominios sean dominios verificados de la organización.
default_role_ids array of strings | null no Reemplaza la lista; null o [] la borra. Las mismas reglas que al crear; solo se comprueban los roles recién añadidos, de modo que un rol que ya estaba en la lista y se eliminó después no bloquea la actualización (se omite al iniciar sesión).
trust_idp_mfa boolean no Solo enterprise.
settings object | null no Se fusiona de forma recursiva (RFC 7396); un miembro null elimina esa clave; null borra toda la configuración. Sin secretos.

Respuesta

200 OK con la conexión actualizada y el nuevo 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"
}

Configuración de clave de acceso

Para type: "passkey" el objeto settings acepta solo las claves indicadas más abajo. Cualquier otra clave, un tipo incorrecto o un valor fuera de rango se rechaza con 422 validation_failed y un errors[].pointer como /settings/max_credentials_per_user. Un valor null significa el valor por defecto. Los errores de forma se notifican antes que los errores de plan.

Clave Tipo Notas
rp_id string Ausente, null o vacío: cada host de inicio de sesión es su propio rpId. En otro caso, el nombre de host de un dominio personalizado active del entorno (en minúsculas, A-label de IDNA); cualquier otro valor da 422 validation_failed (/settings/rp_id). Cuando el entorno ya tenga claves de acceso, cámbielo con Cambiar el rpId de la clave de acceso.
rp_name string Hasta 128 caracteres.
passkey_first_factor_enabled, security_key_second_factor_enabled boolean Por defecto true.
user_verification string preferred (por defecto) o required.
max_credentials_per_user integer De 1 a 20, por defecto 20; las fracciones se rechazan.
require_device_bound_passkeys boolean Sujeto al plan: true requiere Startup.
attestation_required boolean Sujeto al plan: true requiere Enterprise.
aaguid_allowlist, aaguid_blocklist array of UUID strings Como máximo 500 entradas únicas cada una (los errores apuntan a /settings/<key>/<index>). Sujeto al plan: una lista no vacía requiere Enterprise.
related_origins array of strings Orígenes https://host[:port]. Sujeto al plan: una lista no vacía requiere Enterprise.
passkey_enrollment_prompt string off o after_login (por defecto).

Escribir un valor no predeterminado de una clave sujeta al plan falla con 403 plan_feature_unavailable y los miembros feature y required_plan. Hasta que estén disponibles las entitlements del plan, estas claves no se pueden establecer en ningún entorno; escribir un valor por defecto (false, [], null) o eliminar la clave siempre está permitido. Cuando la función esté disponible, cada entrada de related_origins debe ser un dominio personalizado verificado y activo del entorno; en caso contrario la solicitud falla con 422 related_origin_not_verified. La configuración se valida después de aplicar el merge patch, y solo cuando settings forma parte del patch.

Errores

HTTP code Cuándo
400 unknown_field El patch contiene un campo desconocido o de solo lectura.
404 not_found La conexión no existe o pertenece a otro entorno.
409 connection_test_required El patch pone una conexión enterprise en active, o añade un dominio a allowed_email_domains de una conexión active, sin una prueba exitosa de la configuración resultante en las últimas 24 horas (véase Activar una conexión); no se escribe nada. Eliminar dominios no se comprueba.
409 rp_id_change_requires_migration El patch cambia settings.rp_id de una conexión de clave de acceso mientras el entorno tiene claves de acceso que dejarían de funcionar; utilice Cambiar el rpId de la clave de acceso. No se escribe nada.
412 precondition_failed If-Match no coincide con la versión actual.
415 unsupported_media_type El tipo de contenido no es application/merge-patch+json.
422 validation_failed Un valor no es válido o cambió un campo inmutable (code: immutable).
422 related_origin_not_verified Un origen relacionado no es un dominio personalizado verificado del entorno.
403 plan_feature_unavailable El plan no incluye una configuración que usted ha establecido (miembros feature y required_plan), por ejemplo attestation_required.
428 precondition_required Falta la cabecera If-Match.
401 unauthenticated La credencial falta, no es válida o ha sido revocada.
403 insufficient_permissions La credencial no tiene el permiso necesario.
429 rate_limited Se ha superado el límite de uso; reintente después del periodo indicado en Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente (por ejemplo, la comprobación de claves de acceso de un cambio de rp_id no pudo ejecutarse, por lo que no se escribe nada); reintente después del periodo indicado en Retry-After.

Ejemplo

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