# 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`).

```json
{
  "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

```bash
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](/docs/policies/personal-data) 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).