跳到主要内容

与 Management API 交互

什么是 Logto Management API？​

Logto Management API 是一套全面的 API，赋予开发者对实现方案的完全控制，以满足产品需求和技术栈。它是预置的，列在 控制台 > API 资源 > Logto Management API，且无法被删除或修改。

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

备注:

Logto Management API 的标识符在 Logto Cloud 和 Logto 开源版 之间有所不同：

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

在以下示例中，我们将使用 Cloud 版本的标识符。

Logto Management API Resource Logto Management API Details

通过 Logto Management API，你可以访问 Logto 强大的后端服务，这些服务具备高度可扩展性，并可应用于多种场景。它的能力远超 Admin Console 的低代码功能。

以下是一些常用的 API：

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

如何访问 Logto Management API​

创建 M2M 应用​

备注:

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

前往 控制台 > 应用程序，选择“机器对机器”应用类型并开始创建流程。

在创建 M2M 应用程序的过程中，你会被引导到一个页面，在这里你可以为你的应用程序分配 M2M 角色：

分配 M2M 角色弹窗

或者，当你已经创建了 M2M 应用程序后，也可以在 M2M 应用详情页分配这些角色：

分配 M2M 角色页面

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

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

获取访问令牌 (Access token)​

关于访问令牌 (Access token) 请求的基础知识​

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：

App ID and App Secret

获取 Logto Management API 的访问令牌 (Access token)​

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

Logto Management API details

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

信息:

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

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

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(),
  });
};
警告:

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

访问令牌 (Access token) 响应​

成功的访问响应体如下所示：

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

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

使用访问令牌 (Access token) 访问 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 中的所有应用：

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}`,
    },
  });
};

Logto Management API 的典型使用场景​

我们的开发者已经通过 Logto Management API 实现了许多附加功能。我们相信我们的 API 具备极高的可扩展性，可以满足你广泛的需求。以下是一些无法通过 Logto Admin Console 实现，但可以通过 Logto Management API 实现的场景示例。

自定义实现用户资料页​

Logto 目前尚未提供预置的用户资料 UI 方案。我们认识到用户资料与业务和产品属性密切相关。在我们探索最佳方案的同时，建议你使用我们的 API 自行实现。例如，你可以利用我们的交互 API、资料 API 和验证码 API 开发满足你需求的自定义方案。

Logto Admin Console 支持基础的搜索和筛选功能。对于模糊搜索、精确匹配、区分大小写等高级搜索选项，请参考我们的 高级用户搜索 教程和指南。

自定义实现组织管理​

如果你正在使用 组织 (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"

link header 提供了上一页、下一页、第一页和最后一页结果的 URL：

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

使用 total-number header​

除了标准的 link headers，Logto 还会添加一个 Total-Number header：

Total-Number: 216

这对于显示页码非常方便和实用。

更改页码和每页数量​

有两个可选查询参数：

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

速率限制​

备注:

仅适用于 Logto Cloud。

为了确保所有用户服务的可靠性和安全性，我们采用了通用防火墙来监控和管理网站流量。虽然我们没有强制的速率限制，但建议用户每 10 秒内的请求量控制在 200 次以内，以避免触发保护机制。

使用 Logto Management API：分步指南

使用 Postman 快速获取 M2M 访问令牌 (Access token)