Kontoeinstellungen über 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 die Management API nutzen zu müssen. Hier die wichtigsten Punkte:

Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto zuzugreifen und ihr Profil zu verwalten, ohne die Management API zu benötigen.
Verwaltung von Benutzerprofilen und Identitäten: Benutzer können ihr Profil und ihre Sicherheitseinstellungen vollständig verwalten, einschließlich der Möglichkeit, Identitätsinformationen wie E-Mail, Telefon und Passwort zu aktualisieren sowie soziale Verbindungen zu verwalten. MFA und SSO-Unterstützung folgen 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 (Authorization) 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.

Mit der Logto Account API kannst du ein individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das 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 sozialen Verbindungen aktualisieren
MFA-Faktoren (Verifizierungen) verwalten
Benutzersitzungen verwalten

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

hinweis:

SSO-Kontoansicht und Kontolöschungsfunktionen sind derzeit über die Logto Management APIs verfügbar. Siehe Kontoeinstellungen über Management API für Implementierungsdetails.

Wie aktiviere ich die Account API

Navigiere zu Konsole > Anmeldung & Konto > Account Center.

Die Account API ist standardmäßig deaktiviert, daher sind ihre Zugriffskontrollen gesperrt. Aktiviere Account API aktivieren, um sie einzuschalten.

Nach der Aktivierung kannst du die Berechtigungen pro Feld für Identifikatoren, Profildaten und Drittanbieter-Token-Zugriff konfigurieren. Jedes Feld unterstützt Off, ReadOnly oder Edit; der Standardwert ist Off.

Sicherheitsfelder:
- Zu den Feldern gehören: primäre E-Mail, primäres Telefon, soziale Identitäten, Passwort und MFA.
- Bevor Endbenutzer diese Felder bearbeiten, müssen sie ihre Identität per Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungs-ID zu erhalten. Siehe Verifizierungs-ID erhalten.
- Um WebAuthn-Passkeys für MFA zu verwenden, füge die Domains deiner Frontend-App zu WebAuthn Related Origins hinzu, damit Account Center und Anmeldungserlebnis Passkeys teilen können. Siehe Neuen WebAuthn-Passkey verknüpfen.
Profilfelder:
- Zu den Feldern gehören: Benutzername, Name, Avatar, Profil (weitere Standard-Profilattribute) und benutzerdefinierte Daten.
- Endbenutzer können diese Felder ohne zusätzliche Verifizierung bearbeiten.
Secret Vault:
- Für OIDC- oder OAuth-Sozial- und Enterprise-Connectors speichert der Logto Secret Vault Drittanbieter-Zugangs- und Auffrischungstokens sicher nach der Authentifizierung. Apps können dann externe APIs aufrufen, wie z. B. das Synchronisieren von Google-Kalenderereignissen, ohne dass Benutzer sich erneut anmelden müssen. Das Abrufen von Tokens ist automatisch verfügbar, sobald die Account API aktiviert ist.
Sitzungsverwaltung:
- Wenn aktiviert, können Benutzer ihre aktiven Sitzungen einschließlich Geräteinformationen und letzter Anmeldung anzeigen und verwalten. Benutzer können auch Sitzungen widerrufen, um sich von bestimmten Geräten abzumelden.
- Bevor Endbenutzer auf die Sitzungsverwaltung zugreifen, müssen sie ihre Identität per Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungs-ID zu erhalten. Siehe Verifizierungs-ID erhalten.

Wie greife ich auf die Account API zu

hinweis:

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

Zum Beispiel musst du für die POST /api/my-account/primary-email API die email-Berechtigung konfigurieren; für die POST /api/my-account/primary-phone API die phone-Berechtigung.

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

const config: LogtoConfig = {
  // ...andere Optionen
  // Füge die passenden Berechtigungen 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, // Um benutzerdefinierte Daten zu verwalten
    UserScope.Address, // Um Adresse zu verwalten
    UserScope.Identities, // Für Identitäts- und MFA-bezogene APIs
    UserScope.Profile, // Um Benutzerprofil zu verwalten
    UserScope.Sessions, // Um Benutzersitzungen zu verwalten
  ],
};

Zugangstoken abrufen

Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode client.getAccessToken() verwenden, um ein Zugangstoken (Access token) abzurufen. 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 Account API mit Zugangstoken

Du solltest das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) beim Zugriff auf die Account API angeben.

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

Um Benutzerdaten abzurufen, kannst du den GET /api/my-account Endpunkt verwenden.

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

Die Antwort sieht zum Beispiel so aus:

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

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

Grundlegende Kontoinformationen aktualisieren

Zu den grundlegenden Kontoinformationen gehören Benutzername, Name, Avatar, benutzerdefinierte Daten und andere Profilinformationen.

Um Benutzername, Name, Avatar und customData zu aktualisieren, kannst du den PATCH /api/my-account Endpunkt 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 andere Profilinformationen zu aktualisieren, einschließlich familyName, givenName, middleName, nickname, profile (Profilseiten-URL), website, gender, birthdate, zoneinfo, locale und address, kannst du den PATCH /api/my-account/profile Endpunkt 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.

Verifizierungs-ID erhalten

Zuerst musst du eine Verifizierungs-ID mit einer Gültigkeit von 10 Minuten (TTL) erhalten. Diese kann verwendet werden, um die Identität des Benutzers zu verifizieren, bevor sensible Informationen aktualisiert werden. Das bedeutet, sobald ein Benutzer seine Identität erfolgreich per Passwort, E-Mail-Verifizierungscode oder SMS-Verifizierungscode bestätigt hat, hat er 10 Minuten Zeit, um seine authentifizierungsbezogenen Daten wie Identifikatoren, Zugangsdaten, Social Account Linking und MFA zu aktualisieren.

Um eine Verifizierungs-ID zu erhalten, kannst du das Benutzerpasswort verifizieren oder einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden.

Passwort des Benutzers verifizieren

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 zum Beispiel so aus:

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

Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden

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 Verifizierungs-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 zum Beispiel 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 erfolgreicher Verifizierung des Codes kannst du nun die Verifizierungs-ID verwenden, um den Identifikator des Benutzers zu aktualisieren.

Um mehr über Verifizierungen zu erfahren, siehe Sicherheitsverifizierung über Account API.

Anfrage mit Verifizierungs-ID senden

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

Passwort des Benutzers aktualisieren

Um das Passwort des Benutzers zu aktualisieren, kannst du den POST /api/my-account/password Endpunkt verwenden.

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

tipp:

Wie Passwörter, die während der Registrierung erstellt wurden, müssen auch Passwörter, die über die Account API gesetzt werden, der von dir konfigurierten Passwortrichtlinie in Konsole > Sicherheit > Passwortrichtlinie entsprechen. Logto gibt detaillierte Validierungsergebnisse und Fehlermeldungen zurück, wenn das Passwort die Richtlinie nicht erfüllt.

Neue E-Mail aktualisieren oder verknüpfen

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, musst du zuerst den Besitz der E-Mail nachweisen.

Rufe den POST /api/verifications/verification-code Endpunkt 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, den du zur Verifizierung der E-Mail verwendest.

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 erfolgreicher Verifizierung des Codes kannst du nun PATCH /api/my-account/primary-email aufrufen, um die E-Mail des Benutzers zu aktualisieren. Setze die verificationId im Request-Body als newIdentifierVerificationRecordId.

Zwei verschiedene Verifizierungs-IDs:

Für diese Anfrage werden zwei verschiedene Verifizierungs-IDs benötigt:

logto-verification-id (Header): Bestätigt die Identität des Benutzers vor sensiblen Änderungen. Erhalte diese durch Verifizierung des Benutzerpassworts oder Versand eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers.
newIdentifierVerificationRecordId (Body): Bestätigt den Besitz der neuen E-Mail-Adresse. Dies ist die verificationRecordId, die aus dem oben genannten POST /api/verifications/verification-code-Aufruf zurückgegeben wird.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # Bestätigt die Benutzeridentität (durch Passwort oder bestehende E-Mail/Telefon-Verifizierung)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # Die "newIdentifierVerificationRecordId" bestätigt den Besitz der neuen E-Mail (aus dem oben beschriebenen Verifizierungscode-Flow)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

tipp:

Wie E-Mails, die während der Registrierung gesammelt werden, muss jede E-Mail, die über die Account API verknüpft wird, die von dir konfigurierte Blocklist in Konsole > Sicherheit > Blocklist bestehen. Logto lehnt die Anfrage ab und gibt eine detaillierte Fehlermeldung zurück, wenn die E-Mail gegen die Richtlinie verstößt.

E-Mail des Benutzers entfernen

Um die E-Mail des Benutzers zu entfernen, kannst du den DELETE /api/my-account/primary-email Endpunkt 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 PATCH /api/my-account/primary-phone Endpunkt verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den DELETE /api/my-account/primary-phone Endpunkt, um das Telefon des Benutzers zu entfernen.

Um eine neue soziale Verbindung zu verknüpfen, solltest du zuerst eine Autorisierungs-URL mit POST /api/verifications/social 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 Weiterleitungs-URL nach der Autorisierung durch den Benutzer. Du solltest eine Webseite unter dieser URL hosten und den Callback abfangen.
state: Der State, der nach der Autorisierung durch den Benutzer zurückgegeben wird. Es handelt sich um einen zufälligen String, der zur Verhinderung von CSRF-Angriffen verwendet wird.

In der Antwort findest du eine verificationRecordId, die du für später aufbewahren solltest.

Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an die redirectUri mit dem state-Parameter. Dann kannst du den POST /api/verifications/social/verify Endpunkt 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 durch den Benutzer. Du musst die Query-Parameter aus der redirectUri auf deiner Callback-Seite extrahieren und sie als JSON im Feld connectorData übergeben.

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

Zwei verschiedene Verifizierungs-IDs:

Für diese Anfrage werden zwei verschiedene Verifizierungs-IDs benötigt:

logto-verification-id (Header): Bestätigt die Identität des Benutzers vor sensiblen Änderungen. Erhalte diese durch Verifizierung des Benutzerpassworts oder Versand eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers.
newIdentifierVerificationRecordId (Body): Identifiziert die zu verknüpfende soziale Identität. Dies ist die verificationRecordId, die aus dem oben genannten POST /api/verifications/social-Aufruf zurückgegeben wird.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # Bestätigt die Benutzeridentität (durch Passwort oder bestehende E-Mail/Telefon-Verifizierung)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # Die "newIdentifierVerificationRecordId" identifiziert die zu verknüpfende soziale Verbindung (aus dem oben beschriebenen Social-Verification-Flow)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

Um eine soziale Verbindung zu entfernen, kannst du den DELETE /api/my-account/identities Endpunkt 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>'

Neuen WebAuthn-Passkey verknüpfen

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 1: Ursprungs-URL deiner Frontend-App zu den Related Origins hinzufügen

WebAuthn-Passkeys sind an einen bestimmten Hostnamen gebunden, der als Relying Party ID (RP ID) bezeichnet wird. Nur Anwendungen, die auf dem Origin der RP ID gehostet werden, können mit diesen Passkeys registrieren oder authentifizieren.

Da deine Frontend-Anwendung die Account API von einer anderen Domain als die Logto-Authentifizierungsseiten aufruft, musst du Related Origins konfigurieren, um Cross-Origin-Passkey-Operationen zu ermöglichen.

Wie Logto die RP ID bestimmt:

Standard-Setup: Wenn du nur die Standarddomain von Logto https://[tenant-id].logto.app verwendest, ist die RP ID [tenant-id].logto.app
Eigene Domain: Wenn du eine eigene Domain wie https://auth.example.com konfiguriert hast, wird die RP ID zu auth.example.com

Related Origins konfigurieren:

Verwende den PATCH /api/account-center Endpunkt, um den Origin deiner Frontend-Anwendung hinzuzufügen. Wenn das Account Center deiner App z. B. unter https://account.example.com läuft:

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

hinweis:

WebAuthn unterstützt bis zu 5 eindeutige eTLD+1-Labels für Related Origins. Das eTLD+1 (effective top-level domain plus one label) ist der registrierbare Domain-Teil. Zum Beispiel:

https://example.com, https://app.example.com und https://auth.example.com zählen als ein Label (example.com)
https://shopping.com, https://shopping.co.uk und https://shopping.co.jp zählen ebenfalls als ein Label (shopping)
https://example.com und https://another.com zählen als zwei Labels

Wenn du mehr als 5 verschiedene Domains als Related Origins unterstützen musst, siehe die Related Origin Requests Dokumentation für Details.

Schritt 2: Neue Registrierungsoptionen anfordern

Verwende den POST /api/verifications/web-authn/registration Endpunkt, um eine Registrierung für einen neuen Passkey anzufordern. Logto erlaubt es jedem Benutzerkonto, mehrere Passkeys zu registrieren.

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 3: 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 4: Passkey-Registrierung verifizieren

Verwende den POST /api/verifications/web-authn/registration/verify Endpunkt, um die Passkey-Registrierung zu verifizieren.

In diesem Schritt wird die vom Authenticator generierte kryptografische Signatur überprüft, um sicherzustellen, dass der Passkey legitim erstellt wurde und während der Übertragung nicht manipuliert wurde.

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 Verifizierungs-ID.

Schritt 5: Passkey verknüpfen

Schließlich kannst du den Passkey mit dem Benutzerkonto verknüpfen, indem du den POST /api/my-account/mfa-verifications Endpunkt verwendest.

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 Verifizierungs-ID, die durch Verifizierung des bestehenden Faktors des Benutzers erlangt wurde. Siehe Verifizierungs-ID erhalten für Details.
type: Der Typ des MFA-Faktors, aktuell wird nur WebAuthn unterstützt.
newIdentifierVerificationRecordId: Die vom Server in Schritt 1 zurückgegebene Verifizierungs-ID.

Bestehende WebAuthn-Passkeys verwalten

Um bestehende WebAuthn-Passkeys zu verwalten, kannst du den GET /api/my-account/mfa-verifications Endpunkt 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 zum Beispiel 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.

Den Passkey-Namen kannst du mit PATCH /api/my-account/mfa-verifications/{verificationId}/name 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":"..."}'

Den Passkey kannst du mit DELETE /api/my-account/mfa-verifications/{verificationId} 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>'

Neues TOTP verknüpfen

hinweis:

Denke daran, zuerst MFA und TOTP zu aktivieren.

hinweis:

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

Schritt 1: TOTP-Secret generieren

Verwende den POST /api/my-account/mfa-verifications/totp-secret/generate Endpunkt, um ein TOTP-Secret zu generieren.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Die Antwort sieht zum Beispiel so aus:

{
  "secret": "..."
}

Schritt 2: TOTP-Secret dem Benutzer anzeigen

Verwende das Secret, um einen QR-Code zu generieren oder zeige es dem Benutzer direkt an. Der Benutzer sollte es zu seiner Authenticator-App (wie Google Authenticator, Microsoft Authenticator oder Authy) hinzufügen.

Das URI-Format für den QR-Code sollte sein:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Beispiel:

otpauth://totp/YourApp:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Schritt 3: TOTP-Faktor binden

Nachdem der Benutzer das Secret zu seiner Authenticator-App hinzugefügt hat, muss er es verifizieren und an sein Konto binden. Verwende den POST /api/my-account/mfa-verifications Endpunkt, um den TOTP-Faktor zu binden.

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":"Totp","secret":"..."}'

verification_record_id: Eine gültige Verifizierungs-ID, die durch Verifizierung des bestehenden Faktors des Benutzers erlangt wurde. Siehe Verifizierungs-ID erhalten für Details.
type: Muss Totp sein.
secret: Das in Schritt 1 generierte TOTP-Secret.

hinweis:

Ein Benutzer kann nur einen TOTP-Faktor gleichzeitig haben. Wenn der Benutzer bereits einen TOTP-Faktor hat, führt der Versuch, einen weiteren hinzuzufügen, zu einem 422-Fehler.

Backup-Codes verwalten

hinweis:

Denke daran, zuerst MFA und Backup-Codes zu aktivieren.

hinweis:

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

Schritt 1: Neue Backup-Codes generieren

Verwende den POST /api/my-account/mfa-verifications/backup-codes/generate Endpunkt, um einen neuen Satz von 10 Backup-Codes zu generieren.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Die Antwort sieht zum Beispiel so aus:

{
  "codes": ["...", "...", "..."]
}

Schritt 2: Backup-Codes dem Benutzer anzeigen

Bevor die Backup-Codes an das Benutzerkonto gebunden werden, musst du sie dem Benutzer anzeigen und ihn anweisen:

Lade diese Codes sofort herunter oder schreibe sie auf
Bewahre sie an einem sicheren Ort auf
Jeder Code kann nur einmal verwendet werden
Diese Codes sind die letzte Rettung, falls der Benutzer den Zugang zu seinen primären MFA-Methoden verliert

Du solltest die Codes in einem klaren, einfach zu kopierenden Format anzeigen und eine Download-Option (z. B. als Textdatei oder PDF) anbieten.

Schritt 3: Backup-Codes an das Benutzerkonto binden

Verwende den POST /api/my-account/mfa-verifications Endpunkt, um die Backup-Codes an das Benutzerkonto zu binden.

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":"BackupCode","codes":["...","...","..."]}'

verification_record_id: Eine gültige Verifizierungs-ID, die durch Verifizierung des bestehenden Faktors des Benutzers erlangt wurde. Siehe Verifizierungs-ID erhalten für Details.
type: Muss BackupCode sein.
codes: Das Array der im vorherigen Schritt generierten Backup-Codes.

hinweis:

Ein Benutzer kann nur einen Satz Backup-Codes gleichzeitig haben. Wenn alle Codes verwendet wurden, muss der Benutzer neue Codes generieren und binden.
Backup-Codes können nicht der einzige MFA-Faktor sein. Der Benutzer muss mindestens einen weiteren MFA-Faktor (wie WebAuthn oder TOTP) aktiviert haben.
Jeder Backup-Code kann nur einmal verwendet werden.

Vorhandene Backup-Codes anzeigen

Um vorhandene Backup-Codes und deren Nutzungsstatus anzuzeigen, verwende den GET /api/my-account/mfa-verifications/backup-codes Endpunkt:

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

Die Antwort sieht zum Beispiel so aus:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: Der Backup-Code.
usedAt: Der Zeitstempel, wann der Code verwendet wurde, null wenn noch nicht verwendet.

Benutzersitzungen verwalten

Aktive Sitzungen auflisten

Um die aktiven Sitzungen des Benutzers aufzulisten, kannst du den GET /api/my-account/sessions Endpunkt verwenden.

hinweis:

Die Berechtigung UserScope.Sessions ist erforderlich, um auf diesen Endpunkt zuzugreifen.
Das Feld Sessions in den Account Center-Einstellungen muss auf ReadOnly oder Edit gesetzt sein.

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Sitzung nach Sitzungs-ID widerrufen

Um eine bestimmte Sitzung zu widerrufen, verwende den DELETE /api/my-account/sessions/{sessionId} Endpunkt.

hinweis:

Die Berechtigung UserScope.Sessions ist erforderlich, um auf diesen Endpunkt zuzugreifen.
Das Feld Sessions in den Account Center-Einstellungen muss auf Edit gesetzt sein.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Optionale Query-Parameter:

revokeGrantsTarget: Optional kannst du das Ziel der zu widerrufenden Berechtigungen zusammen mit der Sitzung angeben. Mögliche Werte:
- all: Widerruft alle mit der Sitzung verbundenen Berechtigungen.
- firstParty: Widerruft nur Berechtigungen von First-Party-Apps, die mit der Sitzung verbunden sind. (Empfohlen für die meisten Anwendungsfälle, da so der Zugriff für deine eigene App widerrufen wird, während Berechtigungen für Drittanbieter-Apps erhalten bleiben und so ein besseres Benutzererlebnis bieten.)
- nicht angegeben: Das Standardverhalten widerruft Berechtigungen, die nicht den offline_access-Scope haben, was typischerweise bedeutet, dass Nicht-Refresh-Token-Berechtigungen für die Sitzung widerrufen werden.

Was ist die Logto Account API​

Wie aktiviere ich die Account API​

Wie greife ich auf die Account API zu​

Zugangstoken abrufen​

Zugriff auf Account API mit Zugangstoken​

Grundlegende Kontoinformationen verwalten​

Benutzerkontoinformationen abrufen​

Grundlegende Kontoinformationen aktualisieren​

Identifikatoren und andere sensible Informationen verwalten​

Verifizierungs-ID erhalten​

Passwort des Benutzers verifizieren​

Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden​

Anfrage mit Verifizierungs-ID senden​

Passwort des Benutzers aktualisieren​

Neue E-Mail aktualisieren oder verknüpfen​

E-Mail des Benutzers entfernen​

Telefon verwalten​

Neue soziale Verbindung verknüpfen​

Soziale Verbindung entfernen​

Neuen WebAuthn-Passkey verknüpfen​

Bestehende WebAuthn-Passkeys verwalten​

Neues TOTP verknüpfen​

Backup-Codes verwalten​

Benutzersitzungen verwalten​

Was ist die Logto Account API

Wie aktiviere ich die Account API

Wie greife ich auf die Account API zu

Zugangstoken abrufen

Zugriff auf Account API mit Zugangstoken

Grundlegende Kontoinformationen verwalten

Benutzerkontoinformationen abrufen

Grundlegende Kontoinformationen aktualisieren

Identifikatoren und andere sensible Informationen verwalten

Verifizierungs-ID erhalten

Passwort des Benutzers verifizieren

Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden

Anfrage mit Verifizierungs-ID senden

Passwort des Benutzers aktualisieren

Neue E-Mail aktualisieren oder verknüpfen

E-Mail des Benutzers entfernen

Telefon verwalten

Neue soziale Verbindung verknüpfen

Soziale Verbindung entfernen

Neuen WebAuthn-Passkey verknüpfen

Bestehende WebAuthn-Passkeys verwalten

Neues TOTP verknüpfen

Backup-Codes verwalten

Benutzersitzungen verwalten