Eine bestätigte E-Mail-Adresse als primäre Adresse des Benutzers festlegen

POST /v1/users/{user_id}/emails/{email_id}:set-primary · Berechtigung users:write

Macht eine bestätigte Adresse zur primären Adresse des Benutzers; die bisherige primäre Adresse bleibt als sekundäre Adresse erhalten. Eine unbestätigte Adresse kann nicht primär werden. Ist die Adresse bereits primär, wird nichts geschrieben und 200 zurückgegeben. Die Änderung wird als user.primary_email_changed mit dem API-Schlüssel als Akteur im Verwaltungs-Auditprotokoll festgehalten und löst user.updated aus.

Anfrage

Parameter In Erforderlich Beschreibung
user_id path ja Benutzer-ID mit dem Präfix usr_.
email_id path ja ID der E-Mail-Zeile (interne UUID, Kleinbuchstaben, mit Bindestrichen), wie von GET /v1/users/{user_id}/emails zurückgegeben.

Die Anfrage enthält keinen Anfragetext (ein leerer Body oder {} wird akzeptiert).

Antwort

200 OK mit der aktualisierten E-Mail-Zeile. Ohne die Berechtigung users:read_pii wird die Adresse maskiert (a***@e***.com).

{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": true,
  "primary": true,
  "created_at": "2026-01-15T09:30:00Z"
}

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 ist weder leer noch {}.
409 primary_requires_verified Die Adresse ist nicht bestätigt.
404 not_found Der Benutzer oder die E-Mail-Zeile existiert in dieser Umgebung nicht, die E-Mail gehört nicht zu diesem Benutzer, oder eine ID ist fehlerhaft.
401 unauthenticated Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Der Schlüssel besitzt nicht 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/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails/0191f0a0-3333-7444-8555-666666666666:set-primary \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Personenbezogene Daten

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