Testa una connessione

POST /v1/connections/{connection_id}:test · autorizzazione connections:write

Avvia un accesso di prova con la configurazione attuale di una connessione enterprise e restituisce un URL di test. Chi configura la connessione apre l'URL in un browser e accede presso il provider di identità. Il browser torna quindi a return_url con il parametro di query test_id. Leggi l'esito con Ottieni l'ultimo risultato del test.

Un accesso di prova non crea alcuna sessione, non effettua il provisioning di alcun utente e non collega alcun account. Un test superato è necessario per attivare la connessione; modificare la configurazione del provider di identità lo invalida.

Per testare una revisione in bozza invece della configurazione attiva, invia il suo revision_id. La bozza viene sovrapposta alla configurazione attiva solo per questo test (per una migrazione dell'host SP, l'URL di test si trova sul nuovo host). Un test superato di una revisione è la prova richiesta da Pubblica una revisione; non conta come prova di attivazione per la configurazione attiva.

Il test_url è un link al portatore: chiunque lo possieda può eseguire il test entro 10 minuti, una sola volta. Viene restituito solo in questa risposta (Cache-Control: no-store) e non viene mai registrato né sottoposto ad audit. Se ripeti la richiesta con lo stesso Idempotency-Key, la risposta riprodotta non ha test_url e contiene secret_redacted: true; avvia invece un nuovo test. Gli avvii vengono sottoposti ad audit come connection.test_started con solo l'ID del test.

Richiesta

Campo Tipo Obbligatorio Descrizione
connection_id path sì ID della connessione enterprise (conn_…).
return_url string sì URL https assoluto a cui il browser torna dopo il test, lungo al massimo 2048 byte. test_id viene aggiunto come parametro di query.
revision_id string no Una revisione in bozza della connessione (connrev_…) da testare invece della configurazione attiva.

Risposta

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"
}
Campo Descrizione
test_id ID del test (conntest_…).
test_url L'URL da aprire in un browser; valido per 10 minuti e per un solo utilizzo. Non condividerlo né registrarlo. Assente in una risposta riprodotta.
expires_at Quando scade l'URL di test.
secret_redacted true in una risposta riprodotta per lo stesso Idempotency-Key.

Errori

HTTP code Quando
404 not_found La connessione non esiste in questo ambiente oppure non è una connessione enterprise.
409 conflict La connessione non può ancora essere testata (manca la configurazione del protocollo).
422 validation_failed return_url manca o non è un URL https assoluto (errors[] punta a /return_url), oppure revision_id è malformato (invalid_value) o non è una revisione in bozza di questa connessione (not_found; puntatore /revision_id).
400 unknown_field Il corpo contiene un campo sconosciuto.
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha l'autorizzazione richiesta.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo indicato in Retry-After.
503 service_unavailable Una dipendenza non è disponibile temporaneamente; riprova dopo il periodo indicato in Retry-After.

Esempio

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