Pular para o conteúdo principal

Interagir com a Management API

O que é a Logto Management API?​

A Logto Management API é um conjunto abrangente de APIs que oferece aos desenvolvedores controle total sobre sua implementação para atender às necessidades de seus produtos e pilha tecnológica. Ela é pré-construída, listada no Console > API resources > Logto Management API, e não pode ser excluída ou modificada.

Seu identificador segue o padrão https://[tenant-id].logto.app/api

Recurso da Logto Management API Detalhes da Logto Management API

Com a Logto Management API, você pode acessar os robustos serviços de backend do Logto, que são altamente escaláveis e podem ser utilizados em uma variedade de cenários. Ela vai além do que é possível com as capacidades de baixo código do Admin Console.

Algumas APIs frequentemente usadas estão listadas abaixo:

Para saber mais sobre as APIs disponíveis, visite https://openapi.logto.io/.

Como acessar a Logto Management API​

Criar um aplicativo M2M​

nota:

Se você não está familiarizado com o fluxo de autenticação M2M (Máquina para Máquina), recomendamos ler Entendendo o fluxo de autenticação primeiro para entender os conceitos básicos.

Vá para Console > Applications, selecione o tipo de aplicativo "Machine-to-machine" e inicie o processo de criação.

Durante o processo de criação do aplicativo M2M, você será direcionado para uma página onde pode atribuir papéis M2M aos seus aplicativos:

Modal de atribuição de papéis M2M

Ou você também pode atribuir esses papéis na página de detalhes do aplicativo M2M quando já tiver um aplicativo M2M criado:

Página de atribuição de papéis M2M

No módulo de atribuição de papéis, você pode ver que todos os papéis M2M estão incluídos, e os papéis indicados por um ícone do Logto significam que esses papéis incluem permissões da Logto Management API.

Agora atribua papéis M2M que incluem permissões da Logto Management API para o seu aplicativo M2M.

Obter um token de acesso​

Noções básicas sobre solicitação de token de acesso​

O aplicativo M2M faz uma solicitação POST ao endpoint de token para obter um token de acesso, adicionando os seguintes parâmetros usando o formato application/x-www-form-urlencoded no corpo da entidade da solicitação HTTP:

  • grant_type: Deve ser definido como client_credentials
  • resource: O recurso que você deseja acessar
  • scope: O escopo da solicitação de acesso

Você também precisa incluir as credenciais do seu aplicativo M2M no cabeçalho da solicitação para que o endpoint de token autentique seu aplicativo M2M.

Isso é alcançado incluindo as credenciais do aplicativo na forma de autenticação básica (Basic authentication) no cabeçalho de Authorization da solicitação, onde o nome de usuário é o App ID e a senha é o App Secret.

Você pode encontrar o App ID e o App Secret na página de detalhes do seu aplicativo M2M:

App ID e App Secret

Obter token de acesso para a Logto Management API​

Logto fornece um recurso embutido "Logto Management API", é um recurso somente leitura com a permissão all para acessar Logto Management API, você pode vê-lo na sua lista de recursos de API. O indicador de recurso de API está no padrão https://{your-tenant-id}.logto.app/api, e este será o valor do recurso usado no corpo da solicitação do token de acesso.

Detalhes da Logto Management API

Antes de acessar Logto Management API, certifique-se de que seu aplicativo M2M foi atribuído com papéis M2M que incluem a permissão all deste recurso embutido "Logto Management API".

info:

Logto também fornece um papel M2M pré-configurado "Logto Management API access" para novos locatários criados, ao qual a permissão all do recurso Logto Management API já foi atribuída. Você pode usá-lo diretamente sem configurar permissões manualmente. Este papel pré-configurado também pode ser editado e excluído conforme necessário.

Agora, componha tudo o que temos e envie a solicitação:

const logtoEndpoint = 'https://your.logto.endpoint'; // Substitua pelo seu 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(),
  });
};
cuidado:

Para usuários do Logto Cloud: quando você estiver interagindo com Logto Management API, não pode usar domínio personalizado, use o endpoint padrão do Logto https://{your_tenant_id}.logto.app/oidc/token para conceder tokens de acesso.

Resposta do token de acesso​

Um corpo de resposta de acesso bem-sucedido seria assim:

{
  "access_token": "eyJhbG...2g", // Use este token para acessar a Logto Management API
  "expires_in": 3600, // Expiração do token em segundos
  "token_type": "Bearer", // Tipo de autenticação para sua solicitação ao usar o token de acesso
  "scope": "all" // escopo `all` para a Logto Management API
}
nota:

O Logto atualmente não suporta o aplicativo M2M para representar um usuário. O sub no payload do token de acesso será o ID do aplicativo.

Acessar a Logto Management API usando o token de acesso​

Você pode notar que a resposta do token possui um campo token_type, que é fixado como Bearer.

Portanto, você deve colocar o token de acesso no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN) ao interagir com seu servidor de recurso de API.

Usando o token de acesso solicitado com o recurso de API de gerenciamento Logto embutido https://[your-tenant-id].logto.app/api para obter todos os aplicativos no Logto:

const logtoEndpoint = 'https://your.logto.endpoint'; // Substitua pelo seu endpoint Logto
const accessToken = 'eyJhb...2g'; // Token de acesso

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

Cenários típicos para usar a Logto Management API​

Nossos desenvolvedores implementaram muitos recursos adicionais usando a Logto Management API. Acreditamos que nossa API é altamente escalável e pode suportar uma ampla gama de suas necessidades. Aqui estão alguns exemplos de cenários que não são possíveis com o Logto Admin Console, mas podem ser alcançados através da Logto Management API.

Implementar perfil de usuário por conta própria​

Atualmente, o Logto não fornece uma solução de interface de usuário pré-construída para perfis de usuário. Reconhecemos que os perfis de usuário estão intimamente ligados aos atributos de negócios e produtos. Enquanto trabalhamos para determinar a melhor abordagem, sugerimos usar nossas APIs para criar sua própria solução. Por exemplo, você pode utilizar nossa API de interação, API de perfil e API de código de verificação para desenvolver uma solução personalizada que atenda às suas necessidades.

O Logto Admin Console suporta funções básicas de pesquisa e filtragem. Para opções de pesquisa avançada, como pesquisa difusa, correspondência exata e sensibilidade a maiúsculas e minúsculas, confira nossos tutoriais e guias de Pesquisa Avançada de Usuários.

Implementar gerenciamento de organizações por conta própria​

Se você estiver usando o recurso de organizações para construir seu aplicativo multi-tenant, pode precisar da Logto Management API para tarefas como convites para organizações e gerenciamento de membros. Para seu produto SaaS, onde você tem tanto administradores quanto membros no tenant, a Logto Management API pode ajudá-lo a criar um portal de administração personalizado adaptado às suas necessidades de negócios. Confira este para mais detalhes.

Dicas para usar a Logto Management API​

Gerenciando respostas de API paginadas​

Algumas das respostas da API podem incluir muitos resultados, os resultados serão paginados. O Logto fornece 2 tipos de informações de paginação.

Um cabeçalho de resposta paginada será assim:

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

O cabeçalho de link fornece a URL para a página anterior, próxima, primeira e última de resultados:

  • A URL para a página anterior é seguida por rel="prev".
  • A URL para a próxima página é seguida por rel="next".
  • A URL para a última página é seguida por rel="last".
  • A URL para a primeira página é seguida por rel="first".

Usando o cabeçalho total-number​

Além dos cabeçalhos de link padrão, o Logto também adicionará um cabeçalho Total-Number:

Total-Number: 216

Isso seria muito conveniente e útil para mostrar números de página.

Alterando o número da página e o tamanho da página​

Existem 2 parâmetros de consulta opcionais:

  • page: indica o número da página, começa a partir de 1, o valor padrão é 1.
  • page_size: indica o número de itens por página, o valor padrão é 20.

Limite de taxa​

nota:

Isso é apenas para Logto Cloud.

Para garantir a confiabilidade e segurança de nossos serviços para todos os usuários, empregamos um firewall geral que monitora e gerencia o tráfego para nosso site. Embora não imponhamos um limite de taxa estrito, recomendamos que os usuários limitem sua atividade a aproximadamente 200 solicitações a cada 10 segundos para evitar acionar nossas medidas de proteção.

Use Logto Management API: Um guia passo a passo

 Obtenha tokens de acesso M2M em minutos com o Postman