# Esporta i dati di un utente

`POST /v1/users/{user_id}:export` · autorizzazione `users:export`

Avvia un job che raccoglie in un pacchetto i dati personali che KeenAuth conserva su un utente, per una richiesta di accesso o portabilità dell'interessato (GDPR, articoli 15 e 20). Il job viene eseguito in background: interroga [Ottieni un job di esportazione dei dati utente](/docs/api/management/jobs/get-user-export) finché `status` non è `completed`, poi [scarica il pacchetto](/docs/api/management/jobs/download-user-export). All'utente finale non viene inviata alcuna email; consegnargli il pacchetto è una tua responsabilità.

## Richiesta

| Parametro | In | Obbligatorio | Descrizione |
|---|---|---|---|
| `user_id` | path | sì | ID utente, con prefisso `usr_`. |
| `Idempotency-Key` | header | no | Da 16 a 64 caratteri `[A-Za-z0-9_-]`. La stessa chiave dalla stessa credenziale restituisce lo stesso job. |
| `include_ip` | body | no | `true` aggiunge al pacchetto gli indirizzi IP delle sessioni e degli eventi. Richiede anche l'autorizzazione `audit-events:read_ip`. Valore predefinito `false`. |

Il body è facoltativo; invia `{}` oppure non inviare alcun body per un'esportazione senza indirizzi IP.

```json
{ "include_ip": false }
```

## Risposta

`202 Accepted` con il job. Una richiesta ripetuta con la stessa `Idempotency-Key` restituisce il job originale e `Idempotent-Replayed: true`.

```json
{
  "id": "job_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "kind": "subject",
  "source": "management_api",
  "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "status": "queued",
  "include_app_metadata": true,
  "include_ip": false,
  "file": null,
  "failure_reason": null,
  "requested_by": { "type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4b" },
  "created_at": "2026-10-28T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null
}
```

Il pacchetto è un file ZIP:

| File | Contenuto |
|---|---|
| `manifest.json` | Versione dello schema, ID di job e utente, data di creazione, origine e SHA-256 e numero di record di ogni altro file. |
| `profile.json`, `emails.json`, `phones.json` | Campi del profilo, indirizzi email e numeri di telefono. |
| `metadata.json` | `user_metadata` e `app_metadata`. |
| `identities.json` | Identità social e aziendali collegate. |
| `authenticators.json`, `sessions.json` | Passkey e altri autenticatori (senza segreti) e sessioni. |
| `organizations.json`, `oauth_grants.json`, `consents.json` | Appartenenze alle organizzazioni, autorizzazioni OAuth e registrazioni dei consensi. |
| `auth_events.ndjson` | Eventi di autenticazione, un oggetto JSON per riga. |

Gli hash delle password, i seed TOTP, i codici di recupero, i token di sessione e i token SAML o ID grezzi non sono mai inclusi. Il pacchetto viene conservato per 7 giorni dopo il completamento del job.

## Errori

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

| HTTP | `code` | Quando |
|---|---|---|
| 400 | `malformed_request` | Il body o l'header `Idempotency-Key` non è valido. |
| 401 | `unauthenticated` | La chiave API manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La chiave non ha `users:export`, oppure `include_ip` è `true` e la chiave non ha `audit-events:read_ip` (`required_permissions` elenca entrambe). |
| 404 | `not_found` | L'utente non esiste in questo ambiente, oppure l'ID non è valido. |
| 422 | `idempotency_key_reuse` | La `Idempotency-Key` è stata usata con una richiesta diversa. |
| 429 | `rate_limited` | Ci sono troppi job di esportazione in coda o in esecuzione in questo ambiente, oppure è stato superato il limite di richieste; 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/users/usr_01j9xk3m7q8r2s4t6v8w0y2z4a:export \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: dsar-2026-10-28-0001" \
  -H "Content-Type: application/json" \
  -d '{"include_ip": false}'
```

CLI: `keenauth users export usr_01j9xk3m7q8r2s4t6v8w0y2z4a`

## Dati personali

Questo endpoint gestisce dati personali: profilo dell'utente finale. [Dati personali nelle API di KeenAuth](/docs/policies/personal-data) descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene eliminato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.