Interaktion mit Management API

Was ist die Logto Management API?

Die Logto Management API ist eine umfassende Sammlung von APIs, die Entwicklern die vollständige Kontrolle über ihre Implementierung gibt, um sie an ihre Produktanforderungen und ihren Tech-Stack anzupassen. Sie ist vorgefertigt, im Console > API resources > Logto Management API aufgeführt und kann weder gelöscht noch verändert werden.

Ihr Bezeichner folgt dem Muster https://[tenant-id].logto.app/api

hinweis:

Der Bezeichner der Logto Management API unterscheidet sich zwischen Logto Cloud und der Logto Open Source Version:

Logto Cloud: https://[tenant-id].logto.app/api
Logto OSS: https://default.logto.app/api

In den folgenden Beispielen verwenden wir den Bezeichner der Cloud-Version.

Mit der Logto Management API kannst du auf die leistungsstarken Backend-Dienste von Logto zugreifen, die hoch skalierbar sind und in einer Vielzahl von Szenarien genutzt werden können. Sie geht über das hinaus, was mit den Low-Code-Funktionen der Admin Console möglich ist.

Einige häufig genutzte APIs sind unten aufgeführt:

Um mehr über die verfügbaren APIs zu erfahren, besuche bitte https://openapi.logto.io/.

Wie greife ich auf die Logto Management API zu?

Erstelle eine M2M-App

hinweis:

Wenn du mit dem M2M (Maschine-zu-Maschine) Authentifizierungs-Flow nicht vertraut bist, empfehlen wir, zuerst Authentifizierungs-Flow verstehen zu lesen, um die grundlegenden Konzepte zu verstehen.

Gehe zu Console > Applications, wähle den Anwendungstyp "Machine-to-machine" und starte den Erstellungsprozess.

Während des Erstellungsprozesses einer M2M-Anwendung wirst du zu einer Seite weitergeleitet, auf der du M2M-Rollen deinen Anwendungen zuweisen kannst:

Alternativ kannst du diese Rollen auch auf der Detailseite der M2M-Anwendung zuweisen, wenn du bereits eine M2M-Anwendung erstellt hast:

Im Rollenzuweisungsmodul kannst du sehen, dass alle M2M-Rollen enthalten sind, und Rollen, die durch ein Logto-Symbol gekennzeichnet sind, bedeuten, dass diese Rollen Logto Management API Berechtigungen enthalten.

Weise nun deiner M2M-App M2M-Rollen zu, die Logto Management API Berechtigungen enthalten.

Zugangstoken abrufen

Grundlagen zur Zugangstoken-Anfrage

Die M2M-Anwendung macht eine POST-Anfrage an den Token-Endpunkt, um ein Zugangstoken zu erhalten, indem sie die folgenden Parameter im Format application/x-www-form-urlencoded im HTTP-Anfrage-Entity-Body hinzufügt:

grant_type: Muss auf client_credentials gesetzt werden
resource: Die Ressource, auf die du zugreifen möchtest
scope: Die Berechtigung der Zugriffsanfrage

Außerdem musst du die Anmeldeinformationen deiner M2M-Anwendung im Anforderungsheader einfügen, damit der Token-Endpunkt deine M2M-Anwendung authentifizieren kann.

Dies wird erreicht, indem die Anmeldeinformationen der Anwendung im Basic Authentication-Format im Anforderungsheader Authorization eingefügt werden, wobei der Benutzername die App-ID und das Passwort das App-Geheimnis ist.

Du findest die App-ID und das App-Geheimnis auf der Detailseite deiner M2M-Anwendung:

Zugangstoken für Logto Management API abrufen

Logto stellt eine integrierte „Logto Management API“-Ressource bereit. Es handelt sich um eine schreibgeschützte Ressource mit der Berechtigung all, um auf die Logto Management API zuzugreifen. Du findest sie in deiner API-Ressourcenliste. Der Ressourcen-API-Indikator folgt dem Muster https://{your-tenant-id}.logto.app/api und dies ist der Wert, den du im Zugangstoken-Anfrage-Body als Ressource verwendest.

Bevor du auf die Logto Management API zugreifst, stelle sicher, dass deiner M2M-App M2M-Rollen zugewiesen wurden, die die Berechtigung all aus dieser integrierten „Logto Management API“-Ressource enthalten.

info:

Logto stellt außerdem eine vorkonfigurierte „Logto Management API access“-M2M-Rolle für neu erstellte Mandanten bereit, der die Berechtigung all der Logto Management API-Ressource bereits zugewiesen ist. Du kannst sie direkt verwenden, ohne Berechtigungen manuell festzulegen. Diese vorkonfigurierte Rolle kann bei Bedarf auch bearbeitet und gelöscht werden.

Jetzt fasse alles zusammen und sende die Anfrage:

info:

Seit Version v1.30.1 stellt Logto ein offizielles @logto/api Node.js SDK bereit, das dir hilft, einfach mit der Logto Management API zu interagieren.

Node.js mit `@logto/api` SDK
Node.js
cURL

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// Oder du kannst sogar das Abrufen des Zugangstokens überspringen und direkt API-Aufrufe machen
const response = await apiClient.GET('/api/users');
console.log(response.data);

Self-hosted / OSS

OSS-Nutzer sollten default als Tenant-ID verwenden und zusätzlich baseUrl und apiIndicator konfigurieren.

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

const logtoEndpoint = 'https://your.logto.endpoint'; // Ersetze durch deinen Logto-Endpunkt
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};

vorsicht:

Für Logto Cloud-Nutzer: Wenn du mit der Logto Management API interagierst, kannst du keine eigene Domain verwenden. Nutze den Standard-Logto-Endpunkt https://{your_tenant_id}.logto.app/oidc/token, um Zugangstokens zu erhalten.

Zugangstoken-Antwort (Access token response)

Ein erfolgreicher Antwort-Body für das Zugangstoken sieht wie folgt aus:

{
  "access_token": "eyJhbG...2g", // Verwende dieses Token für den Zugriff auf die Logto Management API
  "expires_in": 3600, // Token-Ablaufzeit in Sekunden
  "token_type": "Bearer", // Authentifizierungstyp für deine Anfrage bei Verwendung des Zugangstokens
  "scope": "all" // Berechtigung `all` für die Logto Management API
}

hinweis:

Logto unterstützt derzeit nicht, dass die M2M-App einen Benutzer repräsentiert. Das sub im Zugangstoken-Payload wird die App-ID sein.

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

Denke daran, die Platzhalter durch deine eigenen Werte zu ersetzen.

vorsicht:

Zugangstoken-Antwort (Access token response)

Ein erfolgreicher Antwort-Body für das Zugangstoken sieht wie folgt aus:

{
  "access_token": "eyJhbG...2g", // Verwende dieses Token für den Zugriff auf die Logto Management API
  "expires_in": 3600, // Token-Ablaufzeit in Sekunden
  "token_type": "Bearer", // Authentifizierungstyp für deine Anfrage bei Verwendung des Zugangstokens
  "scope": "all" // Berechtigung `all` für die Logto Management API
}

hinweis:

Logto unterstützt derzeit nicht, dass die M2M-App einen Benutzer repräsentiert. Das sub im Zugangstoken-Payload wird die App-ID sein.

Zugriff auf Logto Management API mit Zugangstoken

Node.js mit `@logto/api` SDK
Node.js
cURL

Mit dem @logto/api SDK kannst du direkt mit jeder Management API interagieren, indem du den folgenden Codeausschnitt verwendest. Das Zugangstoken (Access token) wird intern zwischengespeichert und bei Bedarf automatisch aktualisiert.

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

Du wirst bemerken, dass die Token-Antwort ein token_type-Feld hat, das auf Bearer festgelegt ist.

Daher solltest du das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) platzieren, wenn du mit deinem API-Ressourcenserver interagierst.

const logtoEndpoint = 'https://your.logto.endpoint'; // Ersetze durch deinen Logto-Endpunkt
const accessToken = 'eyJhb...2g'; // Zugangstoken (Access token)

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

Du wirst bemerken, dass die Token-Antwort ein token_type-Feld hat, das auf Bearer festgelegt ist.

Daher solltest du das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) platzieren, wenn du mit deinem API-Ressourcenserver interagierst.

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

Denke daran, die tatsächlichen Werte durch deine eigenen zu ersetzen. Der Wert nach Bearer sollte das Zugangstoken (Access token) (JWT) sein, das du erhalten hast.

Typische Anwendungsfälle für die Logto Management API

Unsere Entwickler haben viele zusätzliche Funktionen mit der Logto Management API implementiert. Wir sind überzeugt, dass unsere API hoch skalierbar ist und eine Vielzahl deiner Anforderungen unterstützen kann. Hier sind einige Beispiele für Szenarien, die mit der Logto Admin Console nicht möglich sind, aber durch die Logto Management API realisiert werden können.

Benutzerprofil selbst implementieren

Logto bietet derzeit keine vorgefertigte UI-Lösung für Benutzerprofile. Wir erkennen an, dass Benutzerprofile eng mit geschäftlichen und produktspezifischen Attributen verbunden sind. Während wir an der besten Lösung arbeiten, empfehlen wir, unsere APIs zu nutzen, um deine eigene Lösung zu erstellen. Du kannst zum Beispiel unsere Interaction API, Profile API und Verification Code API verwenden, um eine individuelle Lösung zu entwickeln, die deinen Anforderungen entspricht.

Erweiterte Benutzersuche

Die Logto Admin Console unterstützt grundlegende Such- und Filterfunktionen. Für erweiterte Suchoptionen wie unscharfe Suche, exakte Übereinstimmung und Groß-/Kleinschreibung, schaue dir unsere Anleitungen zur erweiterten Benutzersuche an.

Organisationsverwaltung selbst implementieren

Wenn du das Organizations Feature nutzt, um deine Multi-Tenant-App zu bauen, benötigst du möglicherweise die Logto Management API für Aufgaben wie Organisationseinladungen und Mitgliederverwaltung. Für dein SaaS-Produkt, bei dem du sowohl Admins als auch Mitglieder im Tenant hast, kann dir die Logto Management API helfen, ein individuelles Admin-Portal zu erstellen, das auf deine Geschäftsanforderungen zugeschnitten ist. Sieh dir dies für weitere Details an.

Tipps zur Nutzung der Logto Management API

Paginierte API-Antworten verwalten

Einige der API-Antworten können viele Ergebnisse enthalten, diese werden paginiert. Logto stellt 2 Arten von Paginierungsinformationen bereit.

Verwendung von Link-Headern

Ein paginierter Antwort-Header sieht wie folgt aus:

Link: <https://logto.dev/users?page=1&page_size=20>; rel="first"

Der Link-Header stellt die URL für die vorherige, nächste, erste und letzte Seite der Ergebnisse bereit:

Die URL für die vorherige Seite folgt auf rel="prev".
Die URL für die nächste Seite folgt auf rel="next".
Die URL für die letzte Seite folgt auf rel="last".
Die URL für die erste Seite folgt auf rel="first".

Verwendung des Total-Number-Headers

Zusätzlich zu den Standard-Link-Headern fügt Logto auch einen Total-Number Header hinzu:

Total-Number: 216

Das ist sehr praktisch und nützlich, um Seitenzahlen anzuzeigen.

Seitenzahl und Seitengröße ändern

Es gibt 2 optionale Query-Parameter:

page: Gibt die Seitenzahl an, beginnt bei 1, Standardwert ist 1.
page_size: Gibt die Anzahl der Elemente pro Seite an, Standardwert ist 20.

Rate Limit

hinweis:

Dies gilt nur für Logto Cloud.

Um die Zuverlässigkeit und Sicherheit unserer Dienste für alle Nutzer zu gewährleisten, setzen wir eine allgemeine Firewall ein, die den Datenverkehr zu unserer Website überwacht und verwaltet. Obwohl wir kein striktes Rate Limit erzwingen, empfehlen wir, die Aktivität auf etwa 200 Anfragen alle 10 Sekunden zu begrenzen, um unsere Schutzmaßnahmen nicht auszulösen.

Logto Management API nutzen: Eine Schritt-für-Schritt-Anleitung

M2M-Zugangstokens in wenigen Minuten mit Postman erhalten

Was ist die Logto Management API?​

Wie greife ich auf die Logto Management API zu?​

Erstelle eine M2M-App​

Zugangstoken abrufen​

Grundlagen zur Zugangstoken-Anfrage​

Zugangstoken für Logto Management API abrufen​

Logto Cloud​

Self-hosted / OSS​

Zugangstoken-Antwort (Access token response)​

Zugangstoken-Antwort (Access token response)​

Zugriff auf Logto Management API mit Zugangstoken​

Typische Anwendungsfälle für die Logto Management API​

Benutzerprofil selbst implementieren​

Erweiterte Benutzersuche​

Organisationsverwaltung selbst implementieren​

Tipps zur Nutzung der Logto Management API​

Paginierte API-Antworten verwalten​

Verwendung von Link-Headern​

Verwendung des Total-Number-Headers​

Seitenzahl und Seitengröße ändern​

Rate Limit​

Verwandte Ressourcen​

Was ist die Logto Management API?

Wie greife ich auf die Logto Management API zu?

Erstelle eine M2M-App

Zugangstoken abrufen

Grundlagen zur Zugangstoken-Anfrage

Zugangstoken für Logto Management API abrufen

Logto Cloud

Self-hosted / OSS

Zugangstoken-Antwort (Access token response)

Zugangstoken-Antwort (Access token response)

Zugriff auf Logto Management API mit Zugangstoken

Typische Anwendungsfälle für die Logto Management API

Benutzerprofil selbst implementieren

Erweiterte Benutzersuche

Organisationsverwaltung selbst implementieren

Tipps zur Nutzung der Logto Management API

Paginierte API-Antworten verwalten

Verwendung von Link-Headern

Verwendung des Total-Number-Headers

Seitenzahl und Seitengröße ändern

Rate Limit

Verwandte Ressourcen