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 na lista de recursos de API no Logto Console, 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 infinidade de cenários. Ela vai além do que é possível com as capacidades de low-code do Admin Console.

Algumas APIs frequentemente usadas estão listadas abaixo:

  • Usuário
  • Aplicativo
  • Logs
  • Papéis (Roles)
  • Recursos
  • Conectores
  • Organizações

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 > Aplicativos, selecione o tipo de aplicativo M2M 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 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.

Pesquisa avançada de usuários​

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ção 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 cabeçalho de número total​

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 número da página e tamanho da página​

Existem 2 parâmetros de consulta opcionais:

  • page: indica o número da página, começa em 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.