# Añadir un certificado de firma del IdP a una conexión

`POST /v1/connections/{connection_id}/certificates` · permiso `connections:write`

Añade a una conexión SAML empresarial un certificado de firma del proveedor de identidad. Úsalo para subir el certificado a mano o para rotar certificados: añade primero el certificado nuevo, cambia el proveedor de identidad al nuevo y después [elimina](delete.md) el antiguo. La rotación surte efecto de inmediato, también en una conexión activa.

El certificado es un único bloque PEM `CERTIFICATE` (como máximo 8 KiB). No debe estar caducado y debe tener una clave RSA de al menos 2048 bits o una clave ECDSA P-256, P-384 o P-521. Cuando se rechaza, la respuesta no indica el motivo y ni el motivo ni el contenido del certificado se registran. Una conexión tiene como máximo 3 certificados activos. Un certificado que se eliminó de la conexión no se puede volver a añadir. La solicitud no admite la cabecera `If-Match`. Las escrituras se auditan como `connection.idp_certificate_added`.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `connection_id` | ruta | sí | ID de la conexión SAML empresarial (`conn_…`). |
| `certificate` | cadena | sí | Un certificado PEM (`-----BEGIN CERTIFICATE-----` …), como máximo 8 KiB. |

## Respuesta

`201 Created` con el certificado nuevo (véase [Listar certificados](list.md)). Cuando el mismo certificado ya está en la conexión, la respuesta es `200 OK` con el certificado registrado; no se escribe ni se audita nada.

```json
{"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
```

## Errores

| HTTP | code | Cuándo |
|---|---|---|
| 404 | `not_found` | La conexión no existe en este entorno o no es una conexión empresarial. |
| 409 | `conflict` | La conexión no es una conexión SAML, todavía no tiene configuración SAML, ya tiene 3 certificados activos o el certificado se eliminó antes de esa conexión. |
| 422 | `validation_failed` | El certificado falta, es demasiado grande o no se acepta; `errors[]` apunta a `/certificate`. Los entornos de staging y producción también rechazan un certificado que coincida con la clave pública de prueba del [servidor simulado local](/docs/cli/mock-server). |
| 400 | `unknown_field` | El cuerpo contiene un campo desconocido. |
| 401 | `unauthenticated` | La credencial falta, no es válida o está revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene el permiso necesario. |
| 429 | `rate_limited` | Se superó el límite de solicitudes; reintenta tras el periodo indicado en `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintenta tras el periodo indicado en `Retry-After`. |

## Ejemplo

```bash
jq -Rs '{certificate: .}' idp-signing.pem > cert.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/certificates" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @cert.json
```

```bash
keenauth connections certificates add conn_01j9xp6q0r1s5t7v9w1x3y5z7b --certificate-file idp-signing.pem
```