Crea un utente

POST /v1/users · autorizzazione users:write

Crea un utente nell'ambiente della chiave API. L'utente appartiene solo a quell'ambiente; lo stesso indirizzo email in due ambienti corrisponde a due utenti distinti. I valori unici (email, phone_number, username, external_id) vengono verificati per ambiente. Invia un header Idempotency-Key per rendere sicuri i tentativi ripetuti.

Richiesta

Il body è un oggetto JSON. I campi sconosciuti vengono rifiutati con unknown_field.

Campo Tipo Obbligatorio Descrizione
email string no* Indirizzo email principale.
email_verified boolean no Segna l'indirizzo email come verificato. Predefinito false.
phone_number string no* Numero di telefono principale in formato E.164.
phone_verified boolean no Segna il numero di telefono come verificato. Predefinito false.
phone_country_code string no Codice ISO 3166-1 alpha-2. Derivato dal prefisso telefonico se vuoto.
username string no* Da 3 a 64 caratteri. Unico nell'ambiente.
external_id string no Il tuo identificatore, da 1 a 255 caratteri. Unico nell'ambiente.
name, given_name, family_name, middle_name, nickname string no Nomi del profilo.
picture, website, profile_url string no URL https://, fino a 2048 caratteri.
locale, zoneinfo, gender, birthdate string no Attributi del profilo. birthdate è YYYY-MM-DD.
address object no Oggetto OIDC address, fino a 2048 byte.
user_metadata, app_metadata object no Oggetti JSON a struttura libera, fino a 16 KiB, profondità 5, 100 chiavi di primo livello.

* È richiesto almeno uno tra email, phone_number o username.

Risposta

201 Created. Il body è l'oggetto utente. L'header ETag contiene la versione dell'utente.

I dati personali vengono mascherati quando la chiave non ha l'autorizzazione users:read_pii: email diventa a***@e***.com, phone_number mantiene solo le ultime 2 cifre (+**********67), name, given_name, family_name, middle_name e nickname diventano iniziali (A. L.), username mantiene solo il primo carattere (a***), birthdate diventa ****-**-** e address diventa {"redacted": true}. user_metadata e app_metadata non vengono mascherati.

{
  "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "kind": "regular",
  "status": "active",
  "external_id": null,
  "username": null,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "email_verified": true,
  "phone_number": null,
  "phone_verified": false,
  "user_metadata": {},
  "app_metadata": {},
  "created_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "last_sign_in_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null
}

Errori

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

HTTP code Quando
400 malformed_request, unknown_field Il body non è JSON valido oppure contiene un campo che non è nello schema.
409 conflict Il valore è già in uso. errors[] indica il campo e il motivo (email_taken, phone_taken, username_taken, external_id_taken).
415 unsupported_media_type Content-Type non è application/json.
422 validation_failed Un valore non è valido; errors[].pointer indica il campo.
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione users:write.
429 rate_limited È stato superato il limite di richieste; rispetta Retry-After.
503 service_unavailable Una dipendenza non è disponibile temporaneamente; riprova più tardi.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/users \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email": "ada@example.com", "email_verified": true, "name": "Ada Lovelace"}'

Dati personali

Questo endpoint tratta dati personali: profilo dell'utente finale. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene cancellato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.