Zum Hauptinhalt springen

Kontoeinstellungen über die Account API

Was ist die Logto Account API​

Die Logto Account API ist eine umfassende Sammlung von APIs, die Endbenutzern direkten API-Zugang ermöglicht, ohne dass sie die Management API durchlaufen müssen. Hier die wichtigsten Punkte:

  • Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto-Profil zuzugreifen und dieses zu verwalten, ohne dass die Management API zwischengeschaltet werden muss.
  • Verwaltung von Benutzerprofilen und Identitäten: Benutzer können ihre Profile und Sicherheitseinstellungen vollständig verwalten, einschließlich der Möglichkeit, Identitätsinformationen wie E-Mail, Telefon und Passwort zu aktualisieren sowie soziale Verbindungen zu verwalten. Unterstützung für MFA und SSO folgt in Kürze.
  • Globale Zugangskontrolle: Administratoren haben vollständige, globale Kontrolle über die Zugriffseinstellungen und können jedes Feld individuell anpassen.
  • Nahtlose Autorisierung (Authorization): Autorisierung ist einfacher denn je! Verwende einfach client.getAccessToken(), um ein opakes Zugangstoken (Opaque token) für OP (Logto) zu erhalten, und füge es dem Authorization-Header als Bearer <access_token> hinzu.
hinweis:

Um sicherzustellen, dass das Zugangstoken die entsprechenden Berechtigungen (Permissions) hat, stelle sicher, dass du die entsprechenden Berechtigungen (Scopes) in deiner Logto-Konfiguration richtig konfiguriert hast.

Zum Beispiel benötigst du für die POST /api/my-account/primary-email API die Berechtigung (Scope) email; für die POST /api/my-account/primary-phone API die Berechtigung (Scope) phone.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...andere Optionen
  // Füge die passenden Berechtigungen (Scopes) hinzu, die zu deinem Anwendungsfall passen.
  scopes: [
    UserScope.Email, // Für `{POST,DELETE} /api/my-account/primary-email` APIs
    UserScope.Phone, // Für `{POST,DELETE} /api/my-account/primary-phone` APIs
    UserScope.CustomData, // Zur Verwaltung benutzerdefinierter Daten
    UserScope.Address, // Zur Verwaltung der Adresse
    UserScope.Identities, // Für Identitäts- und MFA-bezogene APIs
    UserScope.Profile, // Zur Verwaltung des Benutzerprofils
  ],
};

Mit der Logto Account API kannst du ein individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, die vollständig in Logto integriert ist.

Einige häufige Anwendungsfälle sind unten aufgeführt:

  • Benutzerprofil abrufen
  • Benutzerprofil aktualisieren
  • Benutzerpasswort aktualisieren
  • Benutzeridentitäten einschließlich E-Mail, Telefon und sozialer Verbindungen aktualisieren
  • MFA-Faktoren (Verifizierungen) verwalten

Um mehr über die verfügbaren APIs zu erfahren, besuche bitte die Logto Account API Referenz und die Logto Verification API Referenz.

hinweis:

Spezielle Account APIs für die folgenden Einstellungen erscheinen in Kürze: MFA, SSO, benutzerdefinierte Daten (Custom data, user) und Kontolöschung. In der Zwischenzeit kannst du diese Funktionen mit den Logto Management APIs umsetzen. Siehe Kontoeinstellungen über die Management API für weitere Details.

Wie aktiviere ich die Account API​

Standardmäßig ist die Account API deaktiviert. Um sie zu aktivieren, musst du die Management API verwenden, um die globalen Einstellungen zu aktualisieren.

Der API-Endpunkt /api/account-center kann verwendet werden, um die Einstellungen des Account Centers abzurufen und zu aktualisieren. Du kannst ihn nutzen, um die Account API zu aktivieren oder zu deaktivieren und die Felder anzupassen.

Beispielanfrage:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

Das Feld enabled dient zum Aktivieren oder Deaktivieren der Account API, und das Feld fields dient zur Anpassung der Felder. Der Wert kann Off, Edit, ReadOnly sein. Der Standardwert ist Off. Die Liste der Felder:

  • name: Das Namensfeld.
  • avatar: Das Avatar-Feld.
  • profile: Das Profilfeld, einschließlich seiner Unterfelder.
  • username: Das Benutzername-Feld.
  • email: Das E-Mail-Feld.
  • phone: Das Telefonfeld.
  • password: Das Passwortfeld. Beim Abrufen wird true zurückgegeben, wenn der Benutzer ein Passwort gesetzt hat, andernfalls false.
  • social: Soziale Verbindungen.
  • mfa: MFA-Faktoren.

Mehr zu den API-Details findest du in der Logto Management API Referenz.

Wie greife ich auf die Account API zu​

Zugangstoken abrufen​

Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode client.getAccessToken() verwenden, um ein Zugangstoken zu erhalten. Dieses Token ist ein opaker Token (Opaque token), das für den Zugriff auf die Account API verwendet werden kann.

Wenn du das offizielle SDK nicht verwendest, solltest du das resource-Feld für die Zugangstoken-Anfrage an /oidc/token leer lassen.

Zugriff auf die Account API mit Zugangstoken​

Du solltest das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) einfügen, wenn du mit der Account API interagierst.

Hier ein Beispiel, um die Benutzerkontoinformationen abzurufen:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Grundlegende Kontoinformationen verwalten​

Benutzerkontoinformationen abrufen​

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Die Antwort sieht beispielsweise so aus:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

Die Antwortfelder können je nach Account Center-Einstellungen variieren.

Grundlegende Kontoinformationen aktualisieren​

Grundlegende Kontoinformationen umfassen Benutzername, Name, Avatar und Profil.

Um Benutzername, Name und Avatar zu aktualisieren, kannst du den Endpunkt PATCH /api/my-account verwenden.

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

Um das Profil zu aktualisieren, kannst du den Endpunkt PATCH /api/my-account/profile verwenden.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

Identifikatoren und andere sensible Informationen verwalten​

Aus Sicherheitsgründen erfordert die Account API eine zusätzliche Autorisierungsebene für Vorgänge, die Identifikatoren und andere sensible Informationen betreffen.

Eine Verifizierungsdatensatz-ID erhalten​

Zuerst musst du eine Verifizierungsdatensatz-ID erhalten. Diese kann verwendet werden, um die Identität des Benutzers beim Aktualisieren von Identifikatoren zu überprüfen.

Um eine Verifizierungsdatensatz-ID zu erhalten, kannst du das Passwort des Benutzers überprüfen oder einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden.

Mehr zu Verifizierungen findest du unter Sicherheitsverifizierung über die Account API.

Passwort des Benutzers überprüfen​

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

Die Antwort sieht beispielsweise so aus:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Überprüfung durch Senden eines Verifizierungscodes an die E-Mail oder das Telefon des Benutzers​

hinweis:

Um diese Methode zu verwenden, musst du den E-Mail-Connector konfigurieren oder den SMS-Connector konfigurieren und sicherstellen, dass die UserPermissionValidation-Vorlage konfiguriert ist.

Am Beispiel E-Mail: Fordere einen neuen Verifizierungscode an und erhalte die Verifizierungsdatensatz-ID:

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

Die Antwort sieht beispielsweise so aus:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Nach Erhalt des Verifizierungscodes kannst du ihn verwenden, um den Verifizierungsstatus des Verifizierungsdatensatzes zu aktualisieren.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

Nach der Überprüfung des Codes kannst du nun die Verifizierungsdatensatz-ID verwenden, um den Identifikator des Benutzers zu aktualisieren.

Anfrage mit Verifizierungsdatensatz-ID senden​

Wenn du eine Anfrage zum Aktualisieren des Benutzeridentifikators sendest, musst du die Verifizierungsdatensatz-ID im Request-Header mit dem Feld logto-verification-id angeben.

hinweis:

Um diese Methode zu verwenden, musst du den E-Mail-Connector konfigurieren und sicherstellen, dass die BindNewIdentifier-Vorlage konfiguriert ist.

Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, solltest du zuerst den Besitz der E-Mail nachweisen.

Rufe den Endpunkt POST /api/verifications/verification-code auf, um einen Verifizierungscode anzufordern.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

Du findest eine verificationId in der Antwort und erhältst einen Verifizierungscode per E-Mail. Verwende diesen, um die E-Mail zu verifizieren.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

Nach der Verifizierung des Codes kannst du nun die E-Mail des Benutzers aktualisieren. Setze die verificationId im Request-Body als newIdentifierVerificationRecordId.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'

E-Mail des Benutzers entfernen​

Um die E-Mail des Benutzers zu entfernen, kannst du den Endpunkt DELETE /api/my-account/primary-email verwenden.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Telefon verwalten​

hinweis:

Um diese Methode zu verwenden, musst du den SMS-Connector konfigurieren und sicherstellen, dass die BindNewIdentifier-Vorlage konfiguriert ist.

Ähnlich wie beim Aktualisieren der E-Mail kannst du den Endpunkt PATCH /api/my-account/primary-phone verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den Endpunkt DELETE /api/my-account/primary-phone, um das Telefon des Benutzers zu entfernen.

Um eine neue soziale Verbindung zu verknüpfen, solltest du zuerst eine Autorisierungs-URL anfordern:

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'
  • connectorId: Die ID des Social Connectors.
  • redirectUri: Die Redirect-URI, zu der der Benutzer nach der Autorisierung der Anwendung weitergeleitet wird. Du solltest eine Webseite unter dieser URL hosten und den Callback abfangen.
  • state: Der State, der nach der Autorisierung der Anwendung zurückgegeben wird. Es handelt sich um eine zufällige Zeichenkette, die zur Verhinderung von CSRF-Angriffen verwendet wird.

In der Antwort findest du eine verificationRecordId, bewahre sie für die spätere Verwendung auf.

Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an der redirectUri mit dem Parameter state. Dann kannst du den Endpunkt POST /api/verifications/social/verify verwenden, um die soziale Verbindung zu verifizieren.

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

Das connectorData ist die von dem Social Connector zurückgegebene Daten nach der Autorisierung der Anwendung durch den Benutzer. Du musst die Query-Parameter aus der redirectUri auf deiner Callback-Seite extrahieren und sie als JSON im Feld connectorData übergeben.

Abschließend kannst du den Endpunkt POST /api/my-account/identities verwenden, um die soziale Verbindung zu verknüpfen.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"newIdentifierVerificationRecordId":"..."}'

Soziale Verbindung entfernen​

Um eine soziale Verbindung zu entfernen, kannst du den Endpunkt DELETE /api/my-account/identities verwenden.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'
hinweis:

Denke daran, zuerst MFA und WebAuthn zu aktivieren.

hinweis:

Um diese Methode zu verwenden, musst du das Feld mfa in den Account Center-Einstellungen aktivieren.

Schritt 0: Füge den Origin deiner Frontend-App zu den zugehörigen Origins hinzu.

Ein Passkey im Browser ist an einen bestimmten Hostnamen (RP ID) gebunden, und nur der Origin der RP ID kann verwendet werden, um einen Passkey zu registrieren oder zu verifizieren. Da deine Frontend-App, die die Anfrage an die Account API sendet, nicht dieselbe ist wie die Logto-Anmeldeseite, musst du den Origin deiner Frontend-App zur Liste der zugehörigen Origins hinzufügen. Dadurch kann deine Frontend-App einen Passkey unter anderen RP IDs registrieren und verifizieren.

Standardmäßig setzt Logto die RP ID auf die Tenant-Domain, z. B. wenn deine Tenant-Domain https://example.logto.app ist, ist die RP ID example.logto.app. Wenn du eine benutzerdefinierte Domain verwendest, ist die RP ID die benutzerdefinierte Domain, z. B. bei https://auth.example.com ist die RP ID auth.example.com.

Füge nun den Origin deiner Frontend-App zu den zugehörigen Origins hinzu, z. B. wenn dein Frontend-App-Origin https://account.example.com ist:

curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

Mehr zu den zugehörigen Origins findest du in der Related Origin Requests Dokumentation.

Schritt 1: Neue Registrierungsoptionen anfordern.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Du erhältst eine Antwort wie:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Schritt 2: Passkey im lokalen Browser registrieren.

Am Beispiel von @simplewebauthn/browser kannst du die Funktion startRegistration verwenden, um den Passkey im lokalen Browser zu registrieren.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // Die vom Server in Schritt 1 zurückgegebenen Daten
});
// Speichere die Antwort für die spätere Verwendung

Schritt 3: Passkey verifizieren.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'
  • payload: Die Antwort aus dem lokalen Browser in Schritt 2.
  • verificationRecordId: Die vom Server in Schritt 1 zurückgegebene Verifizierungsdatensatz-ID.

Schritt 4: Abschließend kannst du den Passkey verknüpfen.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'
  • verification_record_id: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wird. Siehe den Abschnitt Eine Verifizierungsdatensatz-ID erhalten für weitere Details.
  • type: Der Typ des MFA-Faktors, derzeit wird nur WebAuthn unterstützt.
  • newIdentifierVerificationRecordId: Die vom Server in Schritt 1 zurückgegebene Verifizierungsdatensatz-ID.

Bestehendes WebAuthn-Passkey verwalten​

Um ein bestehendes WebAuthn-Passkey zu verwalten, kannst du den Endpunkt GET /api/my-account/mfa-verifications verwenden, um aktuelle Passkeys und andere MFA-Verifizierungsfaktoren abzurufen.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

Die Antwort sieht beispielsweise so aus:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]
  • id: Die ID der Verifizierung.
  • type: Der Typ der Verifizierung, WebAuthn für WebAuthn-Passkey.
  • name: Der Name des Passkeys, optionales Feld.
  • agent: Der User-Agent des Passkeys.

Passkey-Namen aktualisieren:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Passkey löschen:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'