Sostituisci la politica di età

PUT /v1/age-policy · autorizzazione identity-settings:write

Scrive l'intera politica di età. If-Match è obbligatorio (428 se manca, 412 se non corrisponde); una politica mai scritta ha versione "0". Regole: min_age e soglie per paese sono 13-21; i codici paese sono ISO 3166-1 alpha-2 (maiuscoli), massimo 250 voci; parental_consent_below è null oppure 1..min_age; store_birthdate può essere true solo quando mode è birthdate. La politica si applica solo alle iscrizioni successive; gli utenti esistenti non cambiano.

Richiesta

Corpo JSON (i campi sconosciuti vengono rifiutati con 400 unknown_field):

Campo Tipo Obbligatorio Descrizione
If-Match header sì Intestazione: il valore ETag da GET /v1/age-policy.
mode string sì off, attestation (domanda neutra su anno e mese di nascita, valore non memorizzato) oppure birthdate.
min_age integer sì 13-21.
country_min_age object sì Codice paese → soglia (13-21); i paesi mancanti usano min_age.
country_source string sì ip oppure declared.
under_age_action string sì block oppure create_minor.
parental_consent_below integer | null no null (nessun consenso dei genitori) oppure 1..min_age.
pending_consent_action string sì block_sign_in oppure issue_limited.
store_birthdate boolean sì true solo con mode: birthdate.
applies_to string sì self_signup oppure all.

Risposta

200 OK con la politica e l'intestazione ETag.

{
  "mode": "attestation",
  "min_age": 16,
  "country_min_age": {"DE": 16, "FR": 15, "IT": 14},
  "country_source": "ip",
  "under_age_action": "block",
  "parental_consent_below": null,
  "pending_consent_action": "block_sign_in",
  "store_birthdate": false,
  "applies_to": "self_signup",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Token

Finché mode non è off, gli ID token, gli access token e la risposta UserInfo contengono il age_group dell'utente (adult, minor o unknown) indipendentemente dagli scope richiesti, e parental_consent_status (not_required, pending, granted, denied o revoked) quando ha un valore. Con mode: off non viene emesso nessuno dei due claim. Entrambi sono scritti solo da KeenAuth (hook e template dei claim non possono impostarli); modificali con PATCH /v1/users/{user_id}.

Con pending_consent_action: block_sign_in, un utente il cui parental_consent_status è pending, denied o revoked non riceve alcun token: la richiesta di autorizzazione termina con access_denied e l'endpoint dei token risponde invalid_grant (Parental consent has not been granted.) per i grant authorization code, device code e refresh token. Un refresh token non viene revocato; torna a funzionare quando il consenso è granted. Con issue_limited i token vengono emessi e la tua applicazione limita l'utente tramite i claim.

Errori

HTTP code Quando
400 unknown_field Il corpo contiene un campo sconosciuto.
412 precondition_failed If-Match non corrisponde alla versione attuale.
415 unsupported_media_type Il content type non è application/json.
422 validation_failed Un campo manca (required) o viola una regola sopra; il puntatore indica il campo, per esempio /country_min_age/DE.
428 precondition_required L'intestazione If-Match manca.
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 Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo Retry-After.

Esempio

curl -X PUT https://api.eu.keenauth.com/v1/age-policy \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "0"' \
  -d '{"mode":"attestation","min_age":16,"country_min_age":{"DE":16,"FR":15},"country_source":"ip","under_age_action":"block","parental_consent_below":null,"pending_consent_action":"block_sign_in","store_birthdate":false,"applies_to":"self_signup"}'