Saltar al contenido principal

Interactúa con la Management API

¿Qué es la Logto Management API?​

La Logto Management API es un conjunto completo de APIs que brinda a los desarrolladores control total sobre su implementación para adaptarse a las necesidades de su producto y stack tecnológico. Está preconstruida, listada en Consola > Recursos de API > Logto Management API, y no puede ser eliminada ni modificada.

Su identificador sigue el patrón https://[tenant-id].logto.app/api

nota:

El identificador de la Logto Management API difiere entre Logto Cloud y la versión Logto Open Source:

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

En los siguientes ejemplos, usaremos el identificador de la versión Cloud.

Recurso Logto Management API Detalles de Logto Management API

Con la Logto Management API, puedes acceder a los robustos servicios backend de Logto, que son altamente escalables y pueden ser utilizados en una multitud de escenarios. Va más allá de lo que es posible con las capacidades low-code de la Consola de Administración.

Algunas APIs de uso frecuente se listan a continuación:

Para conocer más sobre las APIs disponibles, visita https://openapi.logto.io/.

Cómo acceder a la Logto Management API​

Crear una app M2M​

nota:

Si no estás familiarizado con el flujo de autenticación M2M (máquina a máquina), te recomendamos leer primero Comprender el flujo de autenticación para entender los conceptos básicos.

Ve a Consola > Aplicaciones, selecciona el tipo de aplicación "Máquina a máquina" y comienza el proceso de creación.

Durante el proceso de creación de una aplicación M2M, serás dirigido a una página donde puedes asignar roles M2M a tus aplicaciones:

Asignar roles M2M modal

O también puedes asignar estos roles en la página de detalles de la aplicación M2M cuando ya tienes una aplicación M2M creada:

Asignar roles M2M página

En el módulo de asignación de roles, puedes ver que todos los roles M2M están incluidos, y los roles indicados con un ícono de Logto significan que estos roles incluyen permisos de Logto Management API.

Ahora asigna roles M2M que incluyan permisos de Logto Management API para tu app M2M.

Obtener un token de acceso​

Conceptos básicos sobre la solicitud de token de acceso​

La aplicación M2M realiza una solicitud POST al endpoint de token para obtener un token de acceso añadiendo los siguientes parámetros utilizando el formato application/x-www-form-urlencoded en el cuerpo de la entidad de la solicitud HTTP:

  • grant_type: Debe establecerse en client_credentials
  • resource: El recurso al que deseas acceder
  • scope: El alcance de la solicitud de acceso

También necesitas incluir las credenciales de tu aplicación M2M en el encabezado de la solicitud para que el endpoint de token autentique tu aplicación M2M.

Esto se logra incluyendo las credenciales de la aplicación en el formulario de autenticación básica en el encabezado de Authorization de la solicitud, donde el nombre de usuario es el App ID y la contraseña es el App Secret.

Puedes encontrar el App ID y el App Secret en la página de detalles de tu aplicación M2M:

App ID and App Secret

Obtener token de acceso para Logto Management API​

Logto proporciona un recurso incorporado "Logto Management API", es un recurso de solo lectura con el permiso all para acceder a Logto Management API, puedes verlo en tu lista de recursos de API. El indicador de API del recurso sigue el patrón https://{your-tenant-id}.logto.app/api, y este será tu valor de recurso utilizado en el cuerpo de la solicitud del token de acceso.

Detalles de Logto Management API

Antes de acceder a Logto Management API, asegúrate de que tu aplicación M2M haya sido asignada con roles M2M que incluyan el permiso all de este recurso incorporado "Logto Management API".

info:

Logto también proporciona un rol M2M preconfigurado "Logto Management API access" para los nuevos inquilinos creados, al cual ya se le ha asignado el permiso all del recurso Logto Management API. Puedes usarlo directamente sin configurar manualmente los permisos. Este rol preconfigurado también puede ser editado y eliminado según sea necesario.

Ahora, compón todo lo que tenemos y envía la solicitud:

const logtoEndpoint = 'https://your.logto.endpoint'; // Reemplaza con tu endpoint de 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(),
  });
};
precaución:

Para los usuarios de Logto Cloud: cuando interactúes con Logto Management API, no puedes usar un dominio personalizado, utiliza el endpoint predeterminado de Logto https://{your_tenant_id}.logto.app/oidc/token para otorgar tokens de acceso.

Respuesta del token de acceso​

Un cuerpo de respuesta de acceso exitoso sería así:

{
  "access_token": "eyJhbG...2g", // Usa este token para acceder a la Logto Management API
  "expires_in": 3600, // Expiración del token en segundos
  "token_type": "Bearer", // Tipo de autenticación para tu solicitud al usar el token de acceso
  "scope": "all" // scope `all` para Logto Management API
}
nota:

Logto actualmente no admite que la aplicación M2M represente a un usuario. El sub en la carga útil del token de acceso será el ID de la aplicación.

Acceder a Logto Management API usando el token de acceso​

Es posible que notes que la respuesta del token tiene un campo token_type, que está fijado a Bearer.

Por lo tanto, debes colocar el token de acceso en el campo Authorization de los encabezados HTTP con el formato Bearer (Bearer YOUR_TOKEN) cuando estés interactuando con tu servidor de recursos de API.

Usando el token de acceso solicitado con el recurso de API de Logto Management incorporado https://[your-tenant-id].logto.app/api para obtener todas las aplicaciones en Logto:

const logtoEndpoint = 'https://your.logto.endpoint'; // Reemplaza con tu endpoint de Logto
const accessToken = 'eyJhb...2g'; // Token de acceso

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

Escenarios típicos para usar Logto Management API​

Nuestros desarrolladores han implementado muchas funciones adicionales usando Logto Management API. Creemos que nuestra API es altamente escalable y puede soportar una amplia gama de necesidades. Aquí tienes algunos ejemplos de escenarios que no son posibles con la Consola de Administración de Logto pero que sí pueden lograrse a través de la Logto Management API.

Implementar el perfil de usuario por tu cuenta​

Actualmente, Logto no proporciona una solución de interfaz preconstruida para perfiles de usuario. Reconocemos que los perfiles de usuario están estrechamente ligados a los atributos del negocio y del producto. Mientras trabajamos en determinar el mejor enfoque, sugerimos usar nuestras APIs para crear tu propia solución. Por ejemplo, puedes utilizar nuestra interaction API, profile API y verification code API para desarrollar una solución personalizada que se adapte a tus necesidades.

La Consola de Administración de Logto admite funciones básicas de búsqueda y filtrado. Para opciones de búsqueda avanzada como búsqueda difusa, coincidencia exacta y sensibilidad a mayúsculas, consulta nuestros tutoriales y guías de Búsqueda avanzada de usuarios.

Implementar la gestión de organizaciones por tu cuenta​

Si estás utilizando la función de organizaciones para construir tu app multi-inquilino, podrías necesitar la Logto Management API para tareas como invitaciones a organizaciones y gestión de miembros. Para tu producto SaaS, donde tienes tanto administradores como miembros en el tenant, la Logto Management API puede ayudarte a crear un portal de administración personalizado adaptado a las necesidades de tu negocio. Consulta esto para más detalles.

Consejos para usar Logto Management API​

Gestión de respuestas paginadas de la API​

Algunas de las respuestas de la API pueden incluir muchos resultados, los resultados serán paginados. Logto proporciona 2 tipos de información de paginación.

Un encabezado de respuesta paginada será así:

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

El encabezado link proporciona la URL para la página anterior, siguiente, primera y última de los resultados:

  • La URL de la página anterior va seguida de rel="prev".
  • La URL de la página siguiente va seguida de rel="next".
  • La URL de la última página va seguida de rel="last".
  • La URL de la primera página va seguida de rel="first".

Uso del encabezado total-number​

Además de los encabezados link estándar, Logto también añadirá un encabezado Total-Number:

Total-Number: 216

Eso será muy conveniente y útil para mostrar números de página.

Cambiar el número de página y el tamaño de página​

Hay 2 parámetros de consulta opcionales:

  • page: indica el número de página, comienza en 1, el valor predeterminado es 1.
  • page_size: indica el número de elementos por página, el valor predeterminado es 20.

Límite de tasa​

nota:

Esto es solo para Logto Cloud.

Para garantizar la fiabilidad y seguridad de nuestros servicios para todos los usuarios, empleamos un firewall general que monitorea y gestiona el tráfico hacia nuestro sitio web. Aunque no aplicamos un límite de tasa estricto, recomendamos que los usuarios limiten su actividad a aproximadamente 200 solicitudes cada 10 segundos para evitar activar nuestras medidas de protección.

Usa Logto Management API: Una guía paso a paso

Obtén tokens de acceso M2M en minutos con Postman