# Aggiungi un certificato di firma IdP a una connessione

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

Aggiunge a una connessione SAML enterprise un certificato di firma del provider di identità. Usala per caricare il certificato a mano o per ruotare i certificati: aggiungi prima il nuovo certificato, passa il provider di identità a quello nuovo, poi [elimina](delete.md) il vecchio. La rotazione ha effetto immediato, anche su una connessione attiva.

Il certificato è un unico blocco PEM `CERTIFICATE` (al massimo 8 KiB). Non deve essere scaduto e deve avere una chiave RSA di almeno 2048 bit oppure una chiave ECDSA P-256, P-384 o P-521. Quando viene rifiutato, la risposta non indica il motivo e né il motivo né il contenuto del certificato vengono registrati. Una connessione ha al massimo 3 certificati attivi. Un certificato eliminato dalla connessione non può essere aggiunto di nuovo. La richiesta non accetta l'header `If-Match`. Le scritture vengono registrate come `connection.idp_certificate_added`.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | percorso | sì | ID della connessione SAML enterprise (`conn_…`). |
| `certificate` | stringa | sì | Un certificato PEM (`-----BEGIN CERTIFICATE-----` …), al massimo 8 KiB. |

## Risposta

`201 Created` con il nuovo certificato (vedi [Elenca i certificati](list.md)). Quando lo stesso certificato è già presente sulla connessione, la risposta è `200 OK` con il certificato registrato; non viene scritto né tracciato nulla.

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

## Errori

| HTTP | code | Quando |
|---|---|---|
| 404 | `not_found` | La connessione non esiste in questo ambiente o non è una connessione enterprise. |
| 409 | `conflict` | La connessione non è una connessione SAML, non ha ancora una configurazione SAML, ha già 3 certificati attivi, oppure il certificato è stato eliminato da essa in precedenza. |
| 422 | `validation_failed` | Il certificato manca, è troppo grande o non viene accettato; `errors[]` indica `/certificate`. Gli ambienti di staging e produzione rifiutano anche un certificato uguale alla chiave pubblica di prova del [server mock locale](/docs/cli/mock-server). |
| 400 | `unknown_field` | Il corpo contiene un campo sconosciuto. |
| 401 | `unauthenticated` | La credenziale è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha il permesso richiesto. |
| 429 | `rate_limited` | È stato superato il limite di frequenza; riprova dopo il periodo indicato da `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato da `Retry-After`. |

## Esempio

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