与 Management API 交互

什么是 Logto Management API？

Logto Management API 是一套全面的 API，开发者可以通过它们完全控制其实现，以满足产品需求和技术栈。它是预构建的，列在 Logto 控制台的 API 资源列表中，不能被删除或修改。

其标识符的模式为 https://[tenant-id].logto.app/api

通过 Logto Management API，你可以访问 Logto 强大的后端服务，这些服务具有高度的可扩展性，可以在多种场景中使用。它超越了管理控制台的低代码能力。

一些常用的 API 列表如下：

用户
应用
日志
角色 (Roles)
资源
连接器 (Connectors)
组织 (Organizations)

要了解更多可用的 API，请访问 https://openapi.logto.io/。

如何访问 Logto Management API

创建一个 M2M 应用

备注

如果你不熟悉 M2M （机器对机器）认证流程，我们建议先阅读理解认证流程以了解基本概念。

前往控制台 > 应用，选择 M2M 应用类型并开始创建过程。

在创建 M2M 应用的过程中，你将被引导到一个页面，在那里你可以为你的应用分配 M2M 角色 (Roles)：

或者，当你已经创建了一个 M2M 应用时，你也可以在 M2M 应用详情页面上分配这些角色 (Roles)：

在角色分配模块中，你可以看到所有 M2M 角色都已包含，带有 Logto 图标的角色表示这些角色包含 Logto Management API 权限。

现在为你的 M2M 应用分配包含 Logto Management API 权限的 M2M 角色。

获取访问令牌

关于访问令牌请求的基础知识

M2M 应用通过向令牌请求端点发送 POST 请求来获取访问令牌 (Access token)，在 HTTP 请求实体主体中使用 application/x-www-form-urlencoded 格式添加以下参数：

grant_type：必须设置为 client_credentials
resource：你想要访问的资源
scope：访问请求的权限 (Scope)

你还需要在请求头中包含 M2M 应用的凭据，以便令牌请求端点认证 (Authentication) 你的 M2M 应用。

这是通过在请求的 Authorization 头中以基本认证 (Basic authentication) 形式包含应用的凭据来实现的，其中用户名是 App ID，密码是 App Secret。

你可以在 M2M 应用的详细信息页面找到 App ID 和 App Secret：

获取 Logto Management API 的访问令牌

Logto 提供了一个内置的 “日志管理 API (Logto Management API)” 资源，它是一个只读资源，具有访问日志管理 API (Logto Management API) 的 all 权限，你可以在你的 API 资源列表中看到它。资源 API 指示器的模式是 https://{your-tenant-id}.logto.app/api ，这将是你在访问令牌请求正文中使用的资源值。

在访问日志管理 API (Logto Management API) 之前，确保你的 M2M 应用已被分配了包含此内置 “日志管理 API (Logto Management API)” 资源的 all 权限的 M2M 角色。

信息

Logto 还为新创建的租户提供了一个预配置的 “日志管理 API (Logto Management API) 访问” M2M 角色，该角色已经分配了日志管理 API (Logto Management API) 资源的所有权限。你可以直接使用它，而无需手动设置权限。这个预配置的角色也可以根据需要进行编辑和删除。

现在，组合我们所有的内容并发送请求：

Node.js
cURL

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

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'

记得用你自己的实际值替换。

警告

对于日志云 (Logto Cloud) 用户：当你与日志管理 API (Logto Management API) 交互时，不能使用自定义域名，请使用默认的 Logto 端点 https://{your_tenant_id}.logto.app/oidc/token 来授予访问令牌。

访问令牌响应

成功的访问响应体如下：

{
  "access_token": "eyJhbG...2g", // 使用此令牌访问 Logto Management API
  "expires_in": 3600, // 令牌过期时间（秒）
  "token_type": "Bearer", // 使用访问令牌时请求的认证类型
  "scope": "all" // Logto Management API 的权限 `all`
}

备注

Logto 目前不支持 M2M 应用表示用户。访问令牌 (Access token) 负载中的 sub 将是应用 ID。

使用访问令牌访问 Logto Management API

你可能会注意到令牌响应中有一个 token_type 字段，它固定为 Bearer。

因此，当你与 API 资源 (API resource) 服务器交互时，应该将访问令牌 (access token) 以 Bearer 格式（Bearer YOUR_TOKEN）放在 HTTP 头的 Authorization 字段中。

使用请求的访问令牌 (Access token) 和内置的 Logto Management API 资源 https://[your-tenant-id].logto.app/api 来获取 Logto 中的所有应用：

Node.js
cURL

const logtoEndpoint = 'https://your.logto.endpoint'; // Replace with your Logto endpoint
const accessToken = 'eyJhb...2g'; // Access Token

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

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

记得用你自己的实际值替换。Bearer 后的值应该是你收到的访问令牌 (JWT)。

使用 Logto Management API 的典型场景

我们的开发者已经使用 Logto Management API 实现了许多附加功能。我们相信我们的 API 具有高度的可扩展性，可以支持你的广泛需求。以下是一些无法通过 Logto 管理控制台实现但可以通过 Logto Management API 实现的场景示例。

自行实现用户资料

Logto 目前不提供用户资料的预构建 UI 解决方案。我们认识到用户资料与业务和产品属性密切相关。在我们努力确定最佳方法的同时，我们建议使用我们的 API 创建你自己的解决方案。例如，你可以利用我们的交互 API、资料 API 和验证码 API 开发满足你需求的自定义解决方案。

高级用户搜索

Logto 管理控制台支持基本的搜索和过滤功能。对于模糊搜索、精确匹配和区分大小写等高级搜索选项，请查看我们的高级用户搜索教程和指南。

自行实现组织管理

如果你正在使用组织 (Organizations) 功能构建多租户应用，你可能需要 Logto Management API 来执行组织邀请和成员管理等任务。对于你的 SaaS 产品，其中租户中有管理员和成员，Logto Management API 可以帮助你创建一个定制的管理员门户，以满足你的业务需求。查看此处了解更多详细信息。

使用 Logto Management API 的提示

管理分页 API 响应

一些 API 响应可能包含许多结果，结果将被分页。Logto 提供两种分页信息。

使用链接头

分页响应头如下：

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

链接头提供了结果的上一页、下一页、第一页和最后一页的 URL：

上一页的 URL 后跟 rel="prev"。
下一页的 URL 后跟 rel="next"。
最后一页的 URL 后跟 rel="last"。
第一页的 URL 后跟 rel="first"。

使用总数头

除了标准的链接头，Logto 还会添加一个 Total-Number 头：

Total-Number: 216

这将非常方便和有用，以显示页码。

更改页码和页面大小

有两个可选的查询参数：

page：表示页码，从 1 开始，默认值为 1。
page_size：表示每页的项目数，默认值为 20。

速率限制

备注

这仅适用于 Logto Cloud。

为了确保我们服务的可靠性和安全性，我们为所有用户部署了一个通用防火墙，用于监控和管理对我们网站的流量。虽然我们不强制执行严格的速率限制，但我们建议用户将其活动限制在大约每 10 秒 200 个请求，以避免触发我们的保护措施。

什么是 Logto Management API？​

如何访问 Logto Management API​

创建一个 M2M 应用​

获取访问令牌​

关于访问令牌请求的基础知识​

获取 Logto Management API 的访问令牌​

访问令牌响应​

使用访问令牌访问 Logto Management API​

使用 Logto Management API 的典型场景​

自行实现用户资料​

高级用户搜索​

自行实现组织管理​

使用 Logto Management API 的提示​

管理分页 API 响应​

使用链接头​

使用总数头​

更改页码和页面大小​

速率限制​