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 den Umweg über die Management API gehen zu 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: Der Admin hat vollständige, globale Kontrolle über die Zugriffseinstellungen und kann jedes Feld individuell anpassen.
  • Nahtlose Autorisierung: Die Autorisierung ist so einfach wie nie! 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 individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das vollständig in Logto integriert ist.

Einige häufige Anwendungsfälle sind:

  • Benutzerprofil abrufen
  • Benutzerprofil aktualisieren
  • Benutzerpasswort aktualisieren
  • Benutzeridentitäten einschließlich E-Mail, Telefon und soziale Verbindungen aktualisieren

Weitere Informationen zu den verfügbaren APIs findest du in der Logto Account API Referenz und der Logto Verification API Referenz.

hinweis:

Spezielle Account APIs für die folgenden Einstellungen erscheinen in Kürze: MFA, SSO, Benutzerdefinierte Daten (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 wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, 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.

Mehr Details zur API 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 abzurufen. Dieses Token ist ein opaker 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) angeben, wenn du mit der Account API interagierst.

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​

Zu den grundlegenden Kontoinformationen gehören 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.

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 oder 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 das Eigentum an 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 zunächst 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 Weiterleitungs-URL, nachdem der Benutzer die Anwendung autorisiert hat. 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 einen zufälligen String, der zur Verhinderung von CSRF-Angriffen verwendet wird.

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

Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an die 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>'