Registra un consenso
POST /v1/users/{user_id}/consent-records · autorizzazione consent-records:write
Registra un'accettazione ottenuta nel tuo canale (method = management_api). Il soggetto è un documento legale (subject_type = document; gli scopi del consenso non sono ancora disponibili) e state è presented, accepted o declined. La versione, l'hash del contenuto e la lingua vengono ricavati dal documento; non puoi fornirli. occurred_at predefinito è l'istante attuale e non può essere nel futuro né più vecchio di 5 minuti. I record sono append-only: non vengono mai aggiornati né eliminati.
Request
Parametri del percorso:
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string | yes | ID utente (usr_…). |
Corpo JSON (i campi sconosciuti vengono rifiutati con 400 unknown_field):
| Field | Type | Required | Description |
|---|---|---|---|
Idempotency-Key |
header | no | Chiave facoltativa (16-64 caratteri) che rende sicura una richiesta ripetuta. |
subject_type |
string | yes | Solo document. |
subject_id |
string | yes | ID del documento legale (ldoc_…) visto dall'utente. |
state |
string | yes | presented, accepted o declined. |
application_id |
string | null | no | Applicazione (app_…); se omesso e il documento è specifico per un'applicazione, viene registrata l'applicazione del documento. |
occurred_at |
string (date-time) | no | Quando è avvenuto; predefinito l'istante attuale, non nel futuro, al massimo 5 minuti fa. |
Response
201 Created con il record di consenso.
{
"id": "crec_01j9xk3m7q8r2s4t6v8w0y2z4b",
"user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c",
"subject_type": "document",
"subject_id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
"subject_version": "2026-10",
"content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"locale": "en",
"state": "accepted",
"method": "management_api",
"application_id": null,
"occurred_at": "2026-10-05T09:31:12.004211Z"
}
Errors
| HTTP | code | Quando |
|---|---|---|
| 400 | unknown_field |
Il corpo contiene un campo sconosciuto. |
| 404 | not_found |
L'utente o application_id non esiste in questo ambiente. L'estensione resource indica quale manca: user o application. |
| 415 | unsupported_media_type |
Il content type non è application/json. |
| 422 | validation_failed |
Un campo non è valido: documento sconosciuto (/subject_id, unknown_subject), subject_type: purpose (not_supported), uno stato non consentito per i documenti, oppure occurred_at fuori intervallo. |
| 401 | unauthenticated |
La credenziale è mancante, non valida o revocata. |
| 403 | insufficient_permissions |
La credenziale non ha l'autorizzazione richiesta. |
| 429 | rate_limited |
È stato superato il limite di frequenza; 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/users/usr_01j9xk3m7q8r2s4t6v8w0y2z4c/consent-records \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"subject_type":"document","subject_id":"ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a","state":"accepted"}'
Dati personali
Questo endpoint contiene dati personali: record di consenso. Dati personali nelle API di KeenAuth 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.