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-Zugriff ermöglicht, ohne die Management API durchlaufen zu müssen. Hier sind die Highlights:

Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihre eigenen Kontoprofile zuzugreifen und diese zu verwalten, ohne die Weiterleitung der Management API zu benötigen.
Benutzerprofil- und Identitätsverwaltung: 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. MFA und SSO-Unterstützung kommen bald.
Globale Zugriffskontrolle: Administratoren haben vollständige, globale Kontrolle über die Zugriffseinstellungen und können jedes Feld anpassen.
Nahtlose Autorisierung: Die Autorisierung ist einfacher denn je! Verwende einfach client.getAccessToken(), um ein opakes Zugangstoken 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 benutzerdefiniertes 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
Benutzersitzungen verwalten
Benutzerautorisierte Apps (Grants) 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 die Management API für Implementierungsdetails.

Wie man die Account API aktiviert

Navigiere zu Konsole > Anmeldung & Konto > Konto-Center.

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

Sobald sie aktiviert ist, konfiguriere die Berechtigungen pro Feld für Identifikatoren, Profildaten und Drittanbieter-Token-Zugriff. Jedes Feld unterstützt Off, ReadOnly oder Edit; der Standard ist Off.

Sicherheitsfelder:
- Felder umfassen: primäre E-Mail, primäres Telefon, soziale Identitäten, Passwort und MFA.
- Bevor Endbenutzer diese Felder bearbeiten, müssen sie ihre Identität über Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungsdatensatz-ID zu erhalten. Siehe Erhalte eine Verifizierungsdatensatz-ID.
- Um WebAuthn-Passkeys für MFA zu verwenden, füge die Domains deiner Frontend-App zu WebAuthn Related Origins hinzu, damit das Konto-Center und die Anmeldungserfahrung Passkeys teilen können. Siehe Verknüpfe einen neuen WebAuthn-Passkey.
Profilfelder:
- Felder umfassen: Benutzername, Name, Avatar, Profil (andere Standardprofilattribute) und benutzerdefinierte Daten.
- Endbenutzer können diese ohne zusätzliche Verifizierung bearbeiten.
Geheimnis-Tresor:
- Für OIDC- oder OAuth-Sozial- und Unternehmens-Connectors speichert Logto Geheimnis-Tresor sicher Drittanbieter-Zugangs- und Auffrischungstokens nach der Authentifizierung. Apps können dann externe APIs aufrufen, wie das Synchronisieren von Google-Kalenderereignissen, ohne die Benutzer erneut zur Anmeldung aufzufordern. Die Token-Abfrage wird automatisch verfügbar, sobald die Account API aktiviert ist.
Sitzungsverwaltung:
- Wenn aktiviert, können Benutzer ihre aktiven Sitzungen anzeigen und verwalten, einschließlich Geräteinformationen und letzter Anmeldezeit. Benutzer können auch Sitzungen widerrufen, um sich von bestimmten Geräten abzumelden.
- Diese gleiche Sessions-Feldberechtigung steuert auch die APIs für benutzerautorisierte Apps (Grants) (Anzeigen und Widerrufen von Grants).
- Bevor Endbenutzer auf die Sitzungsverwaltung zugreifen, müssen sie ihre Identität über Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungsdatensatz-ID zu erhalten. Siehe Erhalte eine Verifizierungsdatensatz-ID.

Wie man auf die Account API zugreift

hinweis:

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

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

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

const config: LogtoConfig = {
  // ...andere Optionen
  // Füge die passenden Berechtigungen hinzu, die zu deinen Anwendungsfällen 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 Adressen zu verwalten
    UserScope.Identities, // Für Identitäts- und MFA-bezogene APIs
    UserScope.Profile, // Um Benutzerprofile zu verwalten
    UserScope.Sessions, // Um Benutzersitzungen und App-Grants zu verwalten
  ],
};

Ein Zugangstoken abrufen

Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode client.getAccessToken() verwenden, um ein Zugangstoken abzurufen. Dieses Token ist ein opakes Token, das verwendet werden kann, um auf die Account API zuzugreifen.

Wenn du das offizielle SDK nicht verwendest, solltest du das resource für die Zugangstoken-Grant-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 ist 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>'

Der Antwortkörper könnte so aussehen:

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

Die Antwortfelder können je nach den Einstellungen des Konto-Centers variieren.

Grundlegende Kontoinformationen aktualisieren

Grundlegende Kontoinformationen umfassen den Benutzernamen, den Namen, den 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 Operationen, die Identifikatoren und andere sensible Informationen betreffen.

Eine Verifizierungsdatensatz-ID erhalten

Zuerst musst du eine Verifizierungsdatensatz-ID mit einer 10-minütigen Ablaufzeit (TTL) erhalten. Diese kann verwendet werden, um die Identität des Benutzers zu verifizieren, bevor sensible Informationen aktualisiert werden. Das bedeutet, dass ein Benutzer, sobald er seine Identität erfolgreich über Passwort, E-Mail-Verifizierungscode oder SMS-Verifizierungscode verifiziert hat, 10 Minuten Zeit hat, um seine authentifizierungsbezogenen Daten zu aktualisieren, einschließlich Identifikatoren, Anmeldeinformationen, sozialer Kontoverknüpfungen und MFA.

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

Das 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":"..."}'

Der Antwortkörper könnte so aussehen:

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

Verifizieren 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.

Nehmen wir E-Mail als Beispiel, 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":"..."}}'

Der Antwortkörper könnte so aussehen:

{
  "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 Verifizierung des Codes kannst du nun die Verifizierungsdatensatz-ID verwenden, um den Identifikator des Benutzers zu aktualisieren.

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

Anfrage mit Verifizierungsdatensatz-ID senden

Wenn du eine Anfrage sendest, um den Identifikator des Benutzers zu aktualisieren, musst du die Verifizierungsdatensatz-ID im Anfrage-Header mit dem logto-verification-id-Feld einfügen.

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:

Genau wie Passwörter, die während der Anmeldung erstellt wurden, müssen Passwörter, die über die Account API festgelegt werden, den Passwortrichtlinien entsprechen, die du in Konsole > Sicherheit > Passwortrichtlinien konfiguriert hast. Logto gibt detaillierte Validierungsergebnisse und Fehlermeldungen zurück, wenn das Passwort die Richtlinien 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, solltest du zuerst das Eigentum 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 wirst eine verificationId in der Antwort finden und einen Verifizierungscode in der E-Mail erhalten, verwende ihn, 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 PATCH /api/my-account/primary-email aufrufen, um die E-Mail des Benutzers zu aktualisieren, setze die verificationId in den Anfragekörper als newIdentifierVerificationRecordId.

Zwei verschiedene Verifizierungsdatensatz-IDs:

Diese Anfrage erfordert zwei separate Verifizierungsdatensatz-IDs:

logto-verification-id (Header): Beweist die Identität des Benutzers, bevor sensible Änderungen vorgenommen werden. Erhalte dies durch Verifizierung des Benutzerpassworts oder Senden eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers.
newIdentifierVerificationRecordId (Body): Beweist das Eigentum an der neuen E-Mail-Adresse. Dies ist die verificationRecordId, die aus dem POST /api/verifications/verification-code Aufruf oben zurückgegeben wird.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # Verifiziert die Benutzeridentität (aus Passwort- oder bestehender E-Mail/Telefon-Verifizierung)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # Die "newIdentifierVerificationRecordId" beweist das Eigentum an der neuen E-Mail (aus dem Verifizierungscode-Fluss oben)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

tipp:

Genau wie E-Mails, die während der Anmeldung gesammelt wurden, muss jede E-Mail, die über die Account API verknüpft wird, die Blocklist Verifizierung bestehen, die du in Konsole > Sicherheit > Blocklist konfiguriert hast. Logto wird die Anfrage ablehnen und einen detaillierten Fehler zurückgeben, wenn die E-Mail gegen die Richtlinien verstößt.

Die 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 verwenden, 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 sozialen Connectors.
redirectUri: Die Umleitungs-URI, nachdem der Benutzer die Anwendung autorisiert hat. Du solltest eine Webseite unter dieser URL hosten und den Rückruf erfassen.
state: Der Zustand, der nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben wird. Es ist eine zufällige Zeichenfolge, die verwendet wird, um CSRF-Angriffe zu verhindern.

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 Rückruf 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":"..."}'

Die connectorData sind die Daten, die vom sozialen Connector nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben werden. Du musst die Abfrageparameter von der redirectUri auf deiner Rückrufseite analysieren und sie als JSON als Wert des connectorData-Feldes einfügen.

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

Zwei verschiedene Verifizierungsdatensatz-IDs:

Diese Anfrage erfordert zwei separate Verifizierungsdatensatz-IDs:

logto-verification-id (Header): Beweist die Identität des Benutzers, bevor sensible Änderungen vorgenommen werden. Erhalte dies durch Verifizierung des Benutzerpassworts oder Senden 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 POST /api/verifications/social Aufruf oben zurückgegeben wird.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # Verifiziert die Benutzeridentität (aus Passwort- oder bestehender 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 sozialen Verifizierungsfluss oben)
  --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>'

Einen neuen WebAuthn-Passkey verknüpfen

hinweis:

Denke daran, zuerst MFA und WebAuthn zu aktivieren.

hinweis:

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

Schritt 1: Füge den Ursprung deiner Frontend-App zu den verwandten Ursprüngen hinzu

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

Da deine Frontend-Anwendung die Account API von einer anderen Domain als Logtos Authentifizierungsseiten aufruft, musst du Verwandte Ursprünge konfigurieren, um Cross-Origin-Passkey-Operationen zu ermöglichen.

Wie Logto die RP ID bestimmt:

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

Verwandte Ursprünge konfigurieren:

Verwende den PATCH /api/account-center Endpunkt, um den Ursprung deiner Frontend-Anwendung hinzuzufügen. Zum Beispiel, wenn das Konto-Center deiner App auf 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 einzigartige eTLD+1 Labels für verwandte Ursprünge. Das eTLD+1 (effektive Top-Level-Domain plus ein 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 auch als ein Label (shopping)
https://example.com und https://another.com zählen als zwei Labels

Wenn du mehr als 5 verschiedene Domains als verwandte Ursprünge unterstützen musst, siehe die Verwandte Ursprungsanfragen Dokumentation für Details.

Schritt 2: Neue Registrierungsoptionen anfordern

Verwende den POST /api/verifications/web-authn/registration Endpunkt, um die Registrierung für einen neuen Passkey anzufordern. Logto erlaubt 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: Registriere den Passkey im lokalen Browser

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

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

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

Schritt 4: Verifiziere die Passkey-Registrierung

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

Dieser Schritt verifiziert die kryptografische Signatur, die vom Authenticator generiert wurde, 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 vom lokalen Browser in Schritt 2.
verificationRecordId: Die Verifizierungsdatensatz-ID, die vom Server in Schritt 1 zurückgegeben wurde.

Schritt 5: Verknüpfe den Passkey

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 Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Du kannst den Abschnitt Erhalte eine Verifizierungsdatensatz-ID für weitere Details einsehen.
type: der Typ des MFA-Faktors, derzeit wird nur WebAuthn unterstützt.
newIdentifierVerificationRecordId: die Verifizierungsdatensatz-ID, die vom Server in Schritt 1 zurückgegeben wurde.

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

Der Antwortkörper könnte so aussehen:

[
  {
    "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 Benutzeragent des Passkeys.

Aktualisiere den Passkey-Namen mit dem PATCH /api/my-account/mfa-verifications/{verificationId}/name Endpunkt:

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

Lösche den Passkey mit dem DELETE /api/my-account/mfa-verifications/{verificationId} Endpunkt:

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

Einen neuen TOTP verknüpfen

hinweis:

Denke daran, zuerst MFA und TOTP zu aktivieren.

hinweis:

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

Schritt 1: Ein TOTP-Geheimnis generieren

Verwende den POST /api/my-account/mfa-verifications/totp-secret/generate Endpunkt, um ein TOTP-Geheimnis 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'

Der Antwortkörper könnte so aussehen:

{
  "secret": "..."
}

Schritt 2: Zeige das TOTP-Geheimnis dem Benutzer an

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

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

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

Beispiel:

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Schritt 3: Binde den TOTP-Faktor

Nachdem der Benutzer das Geheimnis 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 Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Du kannst den Abschnitt Erhalte eine Verifizierungsdatensatz-ID für weitere Details einsehen.
type: muss Totp sein.
secret: das in Schritt 1 generierte TOTP-Geheimnis.

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 mfa-Feld in den Konto-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'

Der Antwortkörper könnte so aussehen:

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

Schritt 2: Zeige die Backup-Codes dem Benutzer an

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

Diese Codes sofort herunterzuladen oder aufzuschreiben
Sie an einem sicheren Ort zu speichern
Zu verstehen, dass jeder Code nur einmal verwendet werden kann
Zu wissen, dass diese Codes ihre letzte Rettung sind, wenn sie den Zugriff auf ihre primären MFA-Methoden verlieren

Du solltest die Codes in einem klaren, leicht kopierbaren Format anzeigen und eine Download-Option (z. B. als Textdatei oder PDF) in Betracht ziehen.

Schritt 3: Binde die Backup-Codes an das Benutzerkonto

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 Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Du kannst den Abschnitt Erhalte eine Verifizierungsdatensatz-ID für weitere Details einsehen.
type: muss BackupCode sein.
codes: das Array der in den vorherigen Schritten generierten Backup-Codes.

hinweis:

Ein Benutzer kann nur einen Satz von 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 anderen 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 ihren 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>'

Der Antwortkörper könnte so aussehen:

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

code: der Backup-Code.
usedAt: der Zeitpunkt, zu dem der Code verwendet wurde, null, wenn er noch nicht verwendet wurde.

Benutzersitzungen verwalten

Aktive Sitzungen auflisten

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

hinweis:

UserScope.Sessions Berechtigung ist erforderlich, um auf diesen Endpunkt zuzugreifen.
Sessions-Feld in den Konto-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:

UserScope.Sessions Berechtigung ist erforderlich, um auf diesen Endpunkt zuzugreifen.
Sessions-Feld in den Konto-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 Abfrageparameter:

revokeGrantsTarget: Optional das Ziel der Grants angeben, die zusammen mit der Sitzung widerrufen werden sollen. Mögliche Werte:
- all: Widerrufe alle Grants, die mit der Sitzung verbunden sind.
- firstParty: Widerrufe nur First-Party-App-Grants, die mit der Sitzung verbunden sind. (Empfohlen für die meisten Anwendungsfälle, da es den Zugriff für deine eigene App widerruft, während Third-Party-App-Grants intakt bleiben, was eine bessere Benutzererfahrung bietet.)
- nicht angegeben: Standardverhalten widerruft Grants, die nicht den offline_access-Bereich haben, was typischerweise bedeutet, dass nicht-Auffrischungstoken-Grants für die Sitzung widerrufen werden.

Benutzerautorisierte Apps (Grants) verwalten

Verwende Benutzerautorisierte Apps (Grants) APIs, wenn Benutzer autorisierte Apps von ihrer Kontoeinstellungsseite aus überprüfen und widerrufen müssen.

hinweis:

App-Grant-APIs teilen dasselbe Berechtigungsmodell wie Sitzungs-APIs.
UserScope.Sessions Berechtigung ist erforderlich.
Sessions-Feld in den Konto-Center-Einstellungen muss aktiviert sein:
- ReadOnly oder Edit, um Grants aufzulisten.
- Edit, um Grants zu widerrufen.

Aktive App-Grants auflisten

Um aktive App-Grants des aktuellen Benutzers aufzulisten, verwende den GET /api/my-account/grants Endpunkt.

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

Optionaler Abfrageparameter:

appType=firstParty: Gibt nur First-Party-App-Grants zurück.
appType=thirdParty: Gibt nur Third-Party-App-Grants zurück.
appType weglassen: Gibt alle aktiven Grants zurück.

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

App-Grant nach Grant-ID widerrufen

Um einen bestimmten App-Grant zu widerrufen, verwende den DELETE /api/my-account/grants/{grantId} Endpunkt.

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

Wenn ein Grant widerrufen wird, werden zuvor ausgegebene opake Zugangstokens und Auffrischungstokens für diesen Grant ungültig.

Was ist die Logto Account API​

Wie man die Account API aktiviert​

Wie man auf die Account API zugreift​

Ein Zugangstoken abrufen​

Zugriff auf die Account API mit Zugangstoken​

Grundlegende Kontoinformationen verwalten​

Benutzerkontoinformationen abrufen​

Grundlegende Kontoinformationen aktualisieren​

Identifikatoren und andere sensible Informationen verwalten​

Eine Verifizierungsdatensatz-ID erhalten​

Das Passwort des Benutzers verifizieren​

Verifizieren durch Senden eines Verifizierungscodes an die E-Mail oder das Telefon des Benutzers​

Anfrage mit Verifizierungsdatensatz-ID senden​

Passwort des Benutzers aktualisieren​

Neue E-Mail aktualisieren oder verknüpfen​

Die E-Mail des Benutzers entfernen​

Telefon verwalten​

Eine neue soziale Verbindung verknüpfen​

Eine soziale Verbindung entfernen​

Einen neuen WebAuthn-Passkey verknüpfen​

Bestehende WebAuthn-Passkeys verwalten​

Einen neuen TOTP verknüpfen​

Backup-Codes verwalten​

Benutzersitzungen verwalten​

Benutzerautorisierte Apps (Grants) verwalten​

Was ist die Logto Account API

Wie man die Account API aktiviert

Wie man auf die Account API zugreift

Ein Zugangstoken abrufen

Zugriff auf die Account API mit Zugangstoken

Grundlegende Kontoinformationen verwalten

Benutzerkontoinformationen abrufen

Grundlegende Kontoinformationen aktualisieren

Identifikatoren und andere sensible Informationen verwalten

Eine Verifizierungsdatensatz-ID erhalten

Das Passwort des Benutzers verifizieren

Verifizieren durch Senden eines Verifizierungscodes an die E-Mail oder das Telefon des Benutzers

Anfrage mit Verifizierungsdatensatz-ID senden

Passwort des Benutzers aktualisieren

Neue E-Mail aktualisieren oder verknüpfen

Die E-Mail des Benutzers entfernen

Telefon verwalten

Eine neue soziale Verbindung verknüpfen

Eine soziale Verbindung entfernen

Einen neuen WebAuthn-Passkey verknüpfen

Bestehende WebAuthn-Passkeys verwalten

Einen neuen TOTP verknüpfen

Backup-Codes verwalten

Benutzersitzungen verwalten

Benutzerautorisierte Apps (Grants) verwalten