# Eine Verbindung testen

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

Startet eine Test-Anmeldung mit der aktuellen Konfiguration einer Enterprise-Verbindung und gibt eine Test-URL zurück. Die Person, die die Verbindung einrichtet, öffnet die URL in einem Browser und meldet sich beim Identitätsanbieter an. Der Browser kehrt danach mit dem Query-Parameter `test_id` zu `return_url` zurück. Das Ergebnis lesen Sie mit [Das neueste Testergebnis abrufen](latest-test-result.md).

Eine Test-Anmeldung erstellt keine Sitzung, legt keinen Benutzer an und verknüpft kein Konto. Ein bestandener Test ist erforderlich, um die Verbindung zu aktivieren; eine Änderung der Konfiguration des Identitätsanbieters macht ihn ungültig.

Um stattdessen eine [Entwurfsrevision](revisions.md) zu testen, senden Sie deren `revision_id`. Der Entwurf wird nur für diesen Test über die aktive Konfiguration gelegt (bei einer SP-Host-Migration befindet sich die Test-URL auf dem neuen Host). Ein bestandener Test einer Revision ist der Nachweis, den [Eine Revision veröffentlichen](publish-revision.md) benötigt; er zählt nicht als Aktivierungsnachweis für die aktive Konfiguration.

Die `test_url` ist ein Bearer-Link: Wer sie besitzt, kann den Test innerhalb von 10 Minuten einmal ausführen. Sie wird nur in dieser Antwort zurückgegeben (`Cache-Control: no-store`) und niemals protokolliert oder auditiert. Wenn Sie die Anfrage mit demselben `Idempotency-Key` wiederholen, enthält die wiederholte Antwort keine `test_url` und trägt `secret_redacted: true`; starten Sie stattdessen einen neuen Test. Starts werden als `connection.test_started` nur mit der Test-ID auditiert.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | path | ja | Enterprise-Verbindungs-ID (`conn_…`). |
| `return_url` | string | ja | Absolute `https`-URL, zu der der Browser nach dem Test zurückkehrt, höchstens 2048 Byte. `test_id` wird als Query-Parameter angehängt. |
| `revision_id` | string | nein | Eine Entwurfsrevision der Verbindung (`connrev_…`), die anstelle der aktiven Konfiguration getestet wird. |

## Antwort

`200 OK`:

```json
{
  "test_id": "conntest_01j9xr4a6b8c0d2e4f6g8h0j2k",
  "test_url": "https://acme.eu1.keenauth.app/sso/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/start?t=…",
  "expires_at": "2026-10-20T10:10:00Z"
}
```

| Feld | Beschreibung |
|---|---|
| `test_id` | Test-ID (`conntest_…`). |
| `test_url` | Die URL, die in einem Browser geöffnet wird; 10 Minuten gültig und einmal verwendbar. Nicht teilen oder protokollieren. Fehlt in einer wiederholten Antwort. |
| `expires_at` | Zeitpunkt, zu dem die Test-URL abläuft. |
| `secret_redacted` | `true` in einer Antwort, die für denselben `Idempotency-Key` wiederholt wurde. |

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht oder ist keine Enterprise-Verbindung. |
| 409 | `conflict` | Die Verbindung kann noch nicht getestet werden (keine Protokollkonfiguration). |
| 422 | `validation_failed` | `return_url` fehlt oder ist keine absolute `https`-URL (`errors[]` verweist auf `/return_url`), oder `revision_id` ist fehlerhaft (`invalid_value`) oder keine Entwurfsrevision dieser Verbindung (`not_found`; Pointer `/revision_id`). |
| 400 | `unknown_field` | Der Body enthält ein unbekanntes Feld. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten haben nicht die erforderliche Berechtigung. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |

## Beispiel

```bash
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:test" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://admin.example.com/sso/test-done"}'
```

```bash
keenauth connections test conn_01j9xp6q0r1s5t7v9w1x3y5z7b --return-url https://admin.example.com/sso/test-done
```