# Caricare un artefatto di supporto

`POST /v1/support-artifacts` · permesso `support-artifacts:write`

Allega un file HAR o un log a un ticket di supporto. Gli artefatti vengono caricati solo dalla pagina Supporto della dashboard; le chiavi API e i client macchina ricevono `403 insufficient_permissions`. La dashboard rimuove i segreti nel tuo browser prima del caricamento, e il server analizza di nuovo l'artefatto: le intestazioni `Cookie`, `Set-Cookie`, `Authorization` e `DPoP`, i campi di token OAuth, OIDC e SAML, i cookie `__Host-`, i JWT e i segreti con prefisso KeenAuth vengono sostituiti con `[redacted]`. Una chiave API di gestione (`idp_sk_`, `idp_rk_`) trovata nell'artefatto viene revocata subito; se la revoca fallisce, non viene memorizzato nulla e il caricamento restituisce `503`. Viene memorizzato solo il contenuto ripulito, cifrato con la chiave dati dell'ambiente, ed eliminato dopo 30 giorni. La risposta non contiene mai il contenuto né i valori rimossi.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `ticket_ref` | query | sì | Riferimento del ticket di supporto: 1-64 caratteri, lettere, cifre e `_ . : -`, che inizia con una lettera o una cifra. |
| `kind` | query | sì | `har` (un documento JSON HAR 1.2) oppure `log` (testo semplice). |
| `Content-Type` | header | sì | `application/octet-stream`. |
| `Content-Encoding` | header | no | `gzip` per inviare un artefatto compresso. |
| `Idempotency-Key` | header | no | Facoltativo. 16-64 caratteri `[A-Za-z0-9_-]`; ripetere la stessa chiave con lo stesso corpo restituisce lo stesso artefatto. |

Il corpo è l'artefatto stesso: al massimo 50 MB non compressi. Il corpo della richiesta sulla rete è limitato a 11 MiB, quindi comprimi con gzip gli artefatti più grandi. Un ticket contiene al massimo 10 artefatti.

## Risposta

`201 Created` con l'artefatto memorizzato. `findings` conta i valori rimossi per tipo; `revocations_triggered` è il numero di credenziali revocate perché comparivano nell'artefatto.

```json
{
  "id": "sart_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "ticket_ref": "SUP-48213",
  "kind": "har",
  "size_bytes": 482113,
  "sha256": "9f2b5c7d1e3a4f60718293a4b5c6d7e8f90123456789abcdef0123456789abcd",
  "findings": {"authorization": 2, "cookie": 5, "host_cookie": 3, "oauth_param": 1},
  "revocations_triggered": 0,
  "created_at": "2026-11-10T09:30:00.123456Z",
  "expires_at": "2026-12-10T09:30:00.123456Z"
}
```

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `malformed_request` | Il corpo non può essere letto, lo stream gzip non è valido oppure `Idempotency-Key` è malformato. |
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La richiesta non è stata fatta dalla dashboard, oppure il ruolo nella dashboard non ha `support-artifacts:write`. |
| 403 | `quota_exceeded` | Il ticket ha già 10 artefatti. |
| 413 | `payload_too_large` | L'artefatto supera 50 MB, oppure il corpo della richiesta supera 11 MiB. |
| 415 | `unsupported_media_type` | `Content-Type` non è `application/octet-stream`, oppure la codifica del contenuto non è `gzip`. |
| 422 | `validation_failed` | `ticket_ref` o `kind` mancano o non sono validi, il corpo è vuoto, oppure un artefatto `har` non è un documento HAR (`/body` `invalid_har`). |
| 422 | `idempotency_key_reuse` | L'`Idempotency-Key` è già stata usata con un corpo diverso. |
| 429 | `rate_limited` | Sono in elaborazione troppi caricamenti oppure è stato superato il limite di frequenza; riprovare dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | L'artefatto non è stato memorizzato (una credenziale non può essere revocata o l'archiviazione non è disponibile); riprovare dopo il periodo indicato in `Retry-After`. |

## Esempio

I caricamenti sono un'azione della dashboard. La richiesta inviata dalla dashboard:

```http
POST /v1/support-artifacts?ticket_ref=SUP-48213&kind=har
Content-Type: application/octet-stream
Content-Encoding: gzip
Idempotency-Key: 2f1c9a7e-5b3d-4e8f-9a6c-1d2e3f4a5b6c

<file HAR compresso con gzip>
```