Saltar al contenido principal

Interactúa con Management API

¿Qué es Logto Management API?​

El 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á preconstruido, listado en el Consola > Recursos de API > Logto Management API, y no se puede eliminar ni modificar.

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

Recurso de Logto Management API Detalles de Logto Management API

Con Logto Management API, puedes acceder a los robustos servicios de 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 de bajo código de la Consola de Administración.

Algunas APIs frecuentemente utilizadas se enumeran a continuación:

Para obtener más información sobre las APIs disponibles, visita https://openapi.logto.io/.

Cómo acceder a Logto Management API​

Crear una aplicación 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 la 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 tengas una aplicación M2M creada:

Asignar roles M2M página

En el módulo de asignación de roles, puedes ver que se incluyen todos los roles M2M, y los roles indicados por un icono 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 aplicación 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 como:

{
  "access_token": "eyJhbG...2g", // Usa este token para acceder a 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" // alcance `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 características adicionales usando Logto Management API. Creemos que nuestra API es altamente escalable y puede soportar una amplia gama de tus necesidades. Aquí hay algunos ejemplos de escenarios que no son posibles con la Consola de Administración de Logto pero que se pueden lograr a través de Logto Management API.

Implementar el perfil de usuario por tu cuenta​

Logto actualmente no proporciona una solución de interfaz de usuario preconstruida para perfiles de usuario. Reconocemos que los perfiles de usuario están estrechamente vinculados a los atributos de negocio y producto. Mientras trabajamos en determinar el mejor enfoque, sugerimos usar nuestras APIs para crear tu propia solución. Por ejemplo, puedes utilizar nuestra API de interacción, API de perfil y API de código de verificación para desarrollar una solución personalizada que satisfaga tus necesidades.

Búsqueda avanzada de usuarios​

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 aplicación multi-tenant, podrías necesitar 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, 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​

Gestionar respuestas de API paginadas​

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

Usando encabezados de enlace​

Un encabezado de respuesta paginada será como:

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

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

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

Usando el encabezado de número total​

Además de los encabezados de enlace estándar, Logto también agregará un encabezado Total-Number:

Total-Number: 216

Eso sería 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 desde 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 a nuestro sitio web. Aunque no imponemos 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.