# IdP-Signaturzertifikat zu einer Verbindung hinzufügen

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

Fügt einer Enterprise-SAML-Verbindung ein Signaturzertifikat des Identity Providers hinzu. Verwenden Sie es, um das Zertifikat von Hand hochzuladen oder um Zertifikate zu rotieren: Fügen Sie zuerst das neue Zertifikat hinzu, stellen Sie den Identity Provider um und [löschen](delete.md) Sie danach das alte. Die Rotation wirkt sofort, auch bei einer aktiven Verbindung.

Das Zertifikat ist ein PEM-Block `CERTIFICATE` (höchstens 8 KiB). Es darf nicht abgelaufen sein und muss einen RSA-Schlüssel mit mindestens 2048 Bit oder einen ECDSA-Schlüssel P-256, P-384 oder P-521 haben. Wird es abgelehnt, nennt die Antwort den Grund nicht, und weder der Grund noch der Zertifikatsinhalt werden protokolliert. Eine Verbindung hat höchstens 3 aktive Zertifikate. Ein von der Verbindung gelöschtes Zertifikat kann nicht erneut hinzugefügt werden. Die Anfrage nimmt keinen `If-Match`-Header an. Schreibvorgänge werden als `connection.idp_certificate_added` auditiert.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | Pfad | ja | ID der Enterprise-SAML-Verbindung (`conn_…`). |
| `certificate` | Zeichenkette | ja | Ein PEM-Zertifikat (`-----BEGIN CERTIFICATE-----` …), höchstens 8 KiB. |

## Antwort

`201 Created` mit dem neuen Zertifikat (siehe [Zertifikate auflisten](list.md)). Ist dasselbe Zertifikat bereits an der Verbindung hinterlegt, lautet die Antwort `200 OK` mit dem registrierten Zertifikat; es wird nichts geschrieben oder auditiert.

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

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht oder ist keine Enterprise-Verbindung. |
| 409 | `conflict` | Die Verbindung ist keine SAML-Verbindung, hat noch keine SAML-Konfiguration, hat bereits 3 aktive Zertifikate oder das Zertifikat wurde zuvor von ihr gelöscht. |
| 422 | `validation_failed` | Das Zertifikat fehlt, ist zu groß oder wird nicht akzeptiert; `errors[]` verweist auf `/certificate`. Staging- und Produktionsumgebungen lehnen außerdem ein Zertifikat ab, das dem öffentlichen Testschlüssel des [lokalen Mock-Servers](/docs/cli/mock-server) entspricht. |
| 400 | `unknown_field` | Der Körper enthält ein unbekanntes Feld. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Den Anmeldedaten fehlt die erforderliche Berechtigung. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie nach der Frist aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie nach der Frist aus `Retry-After`. |

## Beispiel

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