Interagir avec Management API

Qu'est-ce que Logto Management API ?

La Management API de Logto est un ensemble complet d'API qui donne aux développeurs un contrôle total sur leur implémentation afin de répondre à leurs besoins produits et à leur stack technique. Elle est préconfigurée, listée dans Console > Ressources API > Logto Management API, et ne peut pas être supprimée ou modifiée.

Son identifiant suit le modèle https://[tenant-id].logto.app/api

remarque:

L'identifiant de la Management API de Logto diffère entre Logto Cloud et la version Logto Open Source :

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

Dans les exemples suivants, nous utiliserons l'identifiant de la version Cloud.

Avec la Management API de Logto, vous pouvez accéder aux services backend robustes de Logto, qui sont hautement évolutifs et peuvent être utilisés dans de nombreux scénarios. Elle va au-delà de ce qui est possible avec les capacités low-code de la Console d'administration.

Voici quelques API fréquemment utilisées :

Pour en savoir plus sur les API disponibles, veuillez visiter https://openapi.logto.io/.

Comment accéder à Logto Management API

Créer une application M2M

remarque:

Si vous n'êtes pas familier avec le flux d'authentification M2M (Machine à machine), nous vous recommandons de lire d'abord Comprendre le flux d'authentification pour comprendre les concepts de base.

Allez dans Console > Applications, sélectionnez le type d'application "Machine-to-machine" et lancez le processus de création.

Lors du processus de création d'une application M2M, vous serez dirigé vers une page où vous pourrez attribuer des rôles M2M à vos applications :

Vous pouvez également attribuer ces rôles sur la page de détails de l'application M2M lorsque vous avez déjà créé une application M2M :

Dans le module d'attribution des rôles, vous pouvez voir que tous les rôles M2M sont inclus, et les rôles indiqués par une icône Logto signifient que ces rôles incluent des permissions Logto Management API.

Attribuez maintenant des rôles M2M incluant les permissions Logto Management API à votre application M2M.

Récupérer un jeton d’accès

Principes de base sur la requête de jeton d’accès

L'application M2M effectue une requête POST vers le point de terminaison de jeton pour récupérer un jeton d’accès (Access token) en ajoutant les paramètres suivants en utilisant le format application/x-www-form-urlencoded dans le corps de l'entité de la requête HTTP :

grant_type : Doit être défini sur client_credentials
resource : La ressource à laquelle vous souhaitez accéder
scope : La portée de la requête d’accès

Vous devez également inclure les informations d'identification de votre application M2M dans l'en-tête de la requête pour que le point de terminaison de jeton puisse authentifier votre application M2M.

Cela est réalisé en incluant les informations d'identification de l'application dans le formulaire d' Authentification (Basic authentication) dans l'en-tête de la requête Authorization, où le nom d'utilisateur est l'ID de l'application et le mot de passe est le secret de l'application.

Vous pouvez trouver l'ID de l'application et le secret de l'application sur la page des détails de votre application M2M :

ID de l'application et secret de l'application

Récupérer un jeton d’accès pour Logto Management API

Logto fournit une ressource intégrée “Logto Management API”, il s'agit d'une ressource en lecture seule avec la permission all pour accéder à Logto Management API, vous pouvez la voir dans votre liste de ressources API. L’indicateur de ressource API suit le modèle https://{your-tenant-id}.logto.app/api , et ce sera la valeur de ressource à utiliser dans le corps de la requête de jeton d’accès.

Avant d’accéder à Logto Management API, assurez-vous que votre application M2M a été assignée à des rôles M2M incluant la permission all de cette ressource intégrée “Logto Management API”.

info:

Logto fournit également un rôle M2M préconfiguré “Logto Management API access” pour les nouveaux locataires créés, auquel la permission all de la ressource Logto Management API a déjà été attribuée. Vous pouvez l’utiliser directement sans configurer manuellement les permissions. Ce rôle préconfiguré peut également être modifié et supprimé selon les besoins.

Maintenant, rassemblez tout ce que nous avons et envoyez la requête :

info:

Depuis la version v1.30.1, Logto propose un SDK officiel Node.js @logto/api pour vous aider à interagir facilement avec Logto Management API.

Node.js avec le SDK `@logto/api`
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);

// Ou vous pouvez même ignorer la récupération du jeton d’accès et effectuer directement des appels API
const response = await apiClient.GET('/api/users');
console.log(response.data);

Auto-hébergé / OSS

Les utilisateurs OSS doivent utiliser default comme identifiant de locataire, et également fournir les configurations baseUrl et apiIndicator.

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'; // Remplacez par votre endpoint Logto
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(),
  });
};

attention:

Pour les utilisateurs Logto Cloud : lorsque vous interagissez avec Logto Management API, vous ne pouvez pas utiliser de domaine personnalisé, utilisez l’endpoint Logto par défaut https://{your_tenant_id}.logto.app/oidc/token pour obtenir des jetons d’accès.

Réponse du jeton d’accès

Un corps de réponse d’accès réussi serait le suivant :

{
  "access_token": "eyJhbG...2g", // Utilisez ce jeton pour accéder à l’API de gestion Logto
  "expires_in": 3600, // Expiration du jeton en secondes
  "token_type": "Bearer", // Type d’authentification pour votre requête lors de l’utilisation du jeton d’accès
  "scope": "all" // portée `all` pour l’API de gestion Logto
}

remarque:

Logto ne prend pas actuellement en charge l'application M2M pour représenter un utilisateur. Le sub dans la charge utile du jeton d’accès sera l'ID de l'application.

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'

N’oubliez pas de remplacer les valeurs réelles par les vôtres.

attention:

Réponse du jeton d’accès

Un corps de réponse d’accès réussi serait le suivant :

{
  "access_token": "eyJhbG...2g", // Utilisez ce jeton pour accéder à l’API de gestion Logto
  "expires_in": 3600, // Expiration du jeton en secondes
  "token_type": "Bearer", // Type d’authentification pour votre requête lors de l’utilisation du jeton d’accès
  "scope": "all" // portée `all` pour l’API de gestion Logto
}

remarque:

Logto ne prend pas actuellement en charge l'application M2M pour représenter un utilisateur. Le sub dans la charge utile du jeton d’accès sera l'ID de l'application.

Accéder à Logto Management API en utilisant un jeton d’accès

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

Avec le SDK @logto/api, vous pouvez interagir directement avec n'importe quelle Management API en utilisant l'extrait de code ci-dessous. Le jeton d’accès (Access token) est mis en cache en interne et actualisé automatiquement si nécessaire.

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);

Vous pouvez remarquer que la réponse du jeton a un champ token_type, qui est fixé à Bearer.

Ainsi, vous devez placer le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lorsque vous interagissez avec votre serveur de ressource API.

const logtoEndpoint = 'https://your.logto.endpoint'; // Remplacez par votre endpoint Logto
const accessToken = 'eyJhb...2g'; // Jeton d’accès (Access token)

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

Vous pouvez remarquer que la réponse du jeton a un champ token_type, qui est fixé à Bearer.

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

N'oubliez pas de remplacer les valeurs réelles par les vôtres. La valeur après Bearer doit être le jeton d’accès (Access token) (JWT) que vous avez reçu.

Scénarios typiques d’utilisation de Logto Management API

Nos développeurs ont implémenté de nombreuses fonctionnalités supplémentaires en utilisant Logto Management API. Nous pensons que notre API est hautement évolutive et peut répondre à un large éventail de besoins. Voici quelques exemples de scénarios qui ne sont pas possibles avec la Console d'administration Logto mais qui peuvent être réalisés via la Management API de Logto.

Implémenter le profil utilisateur par vous-même

Logto ne propose actuellement pas de solution d'interface utilisateur préconçue pour les profils utilisateurs. Nous reconnaissons que les profils utilisateurs sont étroitement liés aux attributs métier et produit. Pendant que nous travaillons à déterminer la meilleure approche, nous vous suggérons d'utiliser nos API pour créer votre propre solution. Par exemple, vous pouvez utiliser notre interaction API, profile API et verification code API pour développer une solution personnalisée adaptée à vos besoins.

Recherche avancée d’utilisateurs

La Console d'administration Logto prend en charge les fonctions de recherche et de filtrage de base. Pour des options de recherche avancées comme la recherche floue, la correspondance exacte et la sensibilité à la casse, consultez nos tutoriels et guides sur la Recherche avancée d’utilisateurs.

Implémenter la gestion des organisations par vous-même

Si vous utilisez la fonctionnalité organisations pour construire votre application multi-locataire, vous pourriez avoir besoin de la Management API de Logto pour des tâches telles que les invitations d'organisation et la gestion des membres. Pour votre produit SaaS, où vous avez à la fois des administrateurs et des membres dans le locataire, la Management API de Logto peut vous aider à créer un portail d'administration personnalisé adapté à vos besoins métier. Consultez ce guide pour plus de détails.

Conseils pour utiliser Logto Management API

Gérer les réponses paginées des API

Certaines réponses d'API peuvent inclure de nombreux résultats, ceux-ci seront paginés. Logto fournit 2 types d'informations de pagination.

Utilisation des en-têtes link

Un en-tête de réponse paginée ressemblera à ceci :

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

L'en-tête link fournit l'URL pour la page précédente, suivante, première et dernière des résultats :

L'URL de la page précédente est suivie de rel="prev".
L'URL de la page suivante est suivie de rel="next".
L'URL de la dernière page est suivie de rel="last".
L'URL de la première page est suivie de rel="first".

Utilisation de l’en-tête total-number

En plus des en-têtes link standards, Logto ajoutera également un en-tête Total-Number :

Total-Number: 216

Cela est très pratique et utile pour afficher les numéros de page.

Changer le numéro de page et la taille de page

Il existe 2 paramètres de requête optionnels :

page : indique le numéro de page, commence à 1, la valeur par défaut est 1.
page_size : indique le nombre d'éléments par page, la valeur par défaut est 20.

Limite de débit

remarque:

Ceci concerne uniquement Logto Cloud.

Pour garantir la fiabilité et la sécurité de nos services pour tous les utilisateurs, nous utilisons un pare-feu général qui surveille et gère le trafic vers notre site web. Bien que nous n'appliquions pas de limite de débit stricte, nous recommandons aux utilisateurs de limiter leur activité à environ 200 requêtes toutes les 10 secondes afin d'éviter de déclencher nos mesures de protection.

Utiliser Logto Management API : Guide étape par étape

Obtenez des jetons d’accès M2M en quelques minutes avec Postman

Qu'est-ce que Logto Management API ?​

Comment accéder à Logto Management API​

Créer une application M2M​

Récupérer un jeton d’accès​

Principes de base sur la requête de jeton d’accès​

Récupérer un jeton d’accès pour Logto Management API​

Logto Cloud​

Auto-hébergé / OSS​

Réponse du jeton d’accès​

Réponse du jeton d’accès​

Accéder à Logto Management API en utilisant un jeton d’accès​

Scénarios typiques d’utilisation de Logto Management API​

Implémenter le profil utilisateur par vous-même​

Recherche avancée d’utilisateurs​

Implémenter la gestion des organisations par vous-même​

Conseils pour utiliser Logto Management API​

Gérer les réponses paginées des API​

Utilisation des en-têtes link​

Utilisation de l’en-tête total-number​

Changer le numéro de page et la taille de page​

Limite de débit​

Ressources associées​

Qu'est-ce que Logto Management API ?

Comment accéder à Logto Management API

Créer une application M2M

Récupérer un jeton d’accès

Principes de base sur la requête de jeton d’accès

Récupérer un jeton d’accès pour Logto Management API

Logto Cloud

Auto-hébergé / OSS

Réponse du jeton d’accès

Réponse du jeton d’accès

Accéder à Logto Management API en utilisant un jeton d’accès

Scénarios typiques d’utilisation de Logto Management API

Implémenter le profil utilisateur par vous-même

Recherche avancée d’utilisateurs

Implémenter la gestion des organisations par vous-même

Conseils pour utiliser Logto Management API

Gérer les réponses paginées des API

Utilisation des en-têtes link

Utilisation de l’en-tête total-number

Changer le numéro de page et la taille de page

Limite de débit

Ressources associées