# Sospendere un'applicazione

`POST /v1/applications/{application_id}:suspend` · permesso `applications:write`

Imposta lo `status` dell'applicazione su `suspended`. Da quel momento l'applicazione non può più ottenere nuovi token: autorizzazione, PAR, autorizzazione del dispositivo, l'endpoint dei token (incluso il refresh e `client_credentials`), introspection e revoca la rifiutano come client. La sospensione interrompe anche ciò che l'applicazione possiede già: KeenAuth revoca le sue famiglie di refresh token attive aperte prima della sospensione (motivo `client_revoked`) e contrassegna il suo `client_id`, così introspection e userinfo rifiutano i token di accesso emessi all'applicazione prima di quel punto. Un resource server che verifica solo la firma del JWT continua ad accettare tale token di accesso fino alla sua scadenza. Le credenziali client dell'applicazione vengono conservate, quindi per riattivarla non serve un nuovo secret. La richiesta non ha corpo (vuoto o `{}`). Sospendere un'applicazione già sospesa non cambia nulla e restituisce l'applicazione attuale con la stessa versione. La modifica viene scritta nel registro di audit di gestione come `application.updated` e pubblicata come eventi `application_changed` e `application_status_changed`.

## Richiesta

**Intestazioni**: `If-Match: "<version>"` (facoltativa). Con `If-Match` la modifica si applica solo a quella versione (altrimenti `412`); senza, viene usata l'ultima versione e la richiesta viene ripetuta se un altro scrittore modifica l'applicazione nello stesso momento. Invia un'intestazione `Idempotency-Key` per rendere sicuri i tentativi ripetuti.

| Parametro | In | Obbligatorio | Descrizione |
|---|---|---|---|
| `application_id` | path | sì | ID dell'applicazione, con prefisso `app_`. |

## Risposta

`200 OK` con l'applicazione (`"status": "suspended"`) e il suo `ETag`.

## Errori

Ogni errore è un corpo `application/problem+json` con un `code` stabile.

| HTTP | `code` | Quando |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | È stato inviato un corpo non JSON valido oppure con un campo. |
| 401 | `unauthenticated` | La chiave API manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La chiave non ha il permesso `applications:write`. |
| 404 | `not_found` | L'applicazione non esiste in questo ambiente (o l'ID non è valido). |
| 412 | `precondition_failed` | La versione in `If-Match` è obsoleta. |
| 429 | `rate_limited` | È stato superato il limite di frequenza; rispetta `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova più tardi. |

## Esempio

```bash
curl -X POST https://api.eu.keenauth.com/v1/applications/app_6f8d0cjgbmf0gtn2rg6pscp3cg:suspend \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

CLI: `keenauth applications suspend app_6f8d0cjgbmf0gtn2rg6pscp3cg --yes`