Einen Benutzer anlegen

POST /v1/users · Berechtigung users:write

Legt einen Benutzer in der Umgebung des API-Schlüssels an. Der Benutzer gehört nur zu dieser Umgebung; dieselbe E-Mail-Adresse in zwei Umgebungen ergibt zwei getrennte Benutzer. Eindeutige Werte (email, phone_number, username, external_id) werden je Umgebung geprüft. Senden Sie einen Idempotency-Key-Header, damit Wiederholungen sicher sind.

Anfrage

Der Body ist ein JSON-Objekt. Unbekannte Felder werden mit unknown_field abgelehnt.

Feld Typ Pflicht Beschreibung
email string nein* Primäre E-Mail-Adresse.
email_verified boolean nein Markiert die E-Mail-Adresse als bestätigt. Standard false.
phone_number string nein* Primäre Telefonnummer im E.164-Format.
phone_verified boolean nein Markiert die Telefonnummer als bestätigt. Standard false.
phone_country_code string nein ISO-3166-1-Alpha-2-Code. Wird aus dem Telefonpräfix abgeleitet, wenn leer.
username string nein* 3 bis 64 Zeichen. Eindeutig in der Umgebung.
external_id string nein Ihr eigener Bezeichner, 1 bis 255 Zeichen. Eindeutig in der Umgebung.
name, given_name, family_name, middle_name, nickname string nein Profilnamen.
picture, website, profile_url string nein https://-URLs, bis zu 2048 Zeichen.
locale, zoneinfo, gender, birthdate string nein Profilattribute. birthdate ist YYYY-MM-DD.
address object nein OIDC-address-Objekt, bis zu 2048 Byte.
user_metadata, app_metadata object nein Freie JSON-Objekte, bis zu 16 KiB, Tiefe 5, 100 Schlüssel auf oberster Ebene.

* Mindestens eines von email, phone_number oder username ist erforderlich.

Antwort

201 Created. Der Body ist das Benutzerobjekt. Der ETag-Header enthält die Version des Benutzers.

Personenbezogene Daten werden maskiert, wenn dem Schlüssel die Berechtigung users:read_pii fehlt: email wird zu a***@e***.com, phone_number behält nur die letzten 2 Ziffern (+**********67), name, given_name, family_name, middle_name und nickname werden zu Initialen (A. L.), username behält nur das erste Zeichen (a***), birthdate wird zu ****-**-** und address wird zu {"redacted": true}. user_metadata und app_metadata werden nicht maskiert.

{
  "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
}

Fehler

Jeder Fehler ist ein application/problem+json-Body mit einem stabilen code.

HTTP code Wann
400 malformed_request, unknown_field Der Body ist kein gültiges JSON oder enthält ein Feld, das nicht im Schema vorkommt.
409 conflict Der Wert ist bereits belegt. errors[] nennt das Feld und den Grund (email_taken, phone_taken, username_taken, external_id_taken).
415 unsupported_media_type Content-Type ist nicht application/json.
422 validation_failed Ein Wert ist ungültig; errors[].pointer nennt das Feld.
401 unauthenticated Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Dem Schlüssel fehlt die Berechtigung users:write.
429 rate_limited Das Ratenlimit wurde überschritten; beachten Sie Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut.

Beispiel

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"}'

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Profil des Endbenutzers. Personenbezogene Daten in den KeenAuth-APIs beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).