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.
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 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 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:
{
"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
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"}'
keenauth connections test conn_01j9xp6q0r1s5t7v9w1x3y5z7b --return-url https://admin.example.com/sso/test-done