# 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](latest-test-result.md).

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](revisions.md) 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](publish-revision.md); 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`:

```json
{
  "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

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