与 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，你可以访问 Logto 强大的后端服务，这些服务具有高度可扩展性，并可用于多种场景。它超越了管理控制台低代码能力的限制。

以下是一些常用的 API：

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

如何访问 Logto Management API

创建 M2M 应用

备注:

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

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

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

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

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

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

获取访问令牌 (Access token)

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

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

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

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

这可以通过在请求的 Authorization 头中以 Basic 认证 (Authentication) 形式包含应用凭据来实现：将 {App ID}:{App Secret} 进行 base64 编码，并将其作为 Basic 前缀后的值。

你可以在 M2M 应用的详情页找到 App ID 和 App Secret：

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

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

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

信息:

Logto 还为新创建的租户预配置了 “Logto Management API access” M2M 角色 (Role)，该角色已分配了 Logto Management API 资源的 all 权限。你可以直接使用，无需手动设置权限。此预配置角色也可以根据需要进行编辑和删除。

现在，将以上内容组合起来并发送请求：

信息:

自 v1.30.1 版本起，Logto 提供了官方的 @logto/api Node.js SDK，帮助你轻松与 Logto Management API 交互。

Node.js with `@logto/api` SDK
Node.js
cURL

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// 或者你甚至可以跳过获取访问令牌 (Access token)，直接调用 API
const response = await apiClient.GET('/api/users');
console.log(response.data);

自托管 / OSS

OSS 用户应使用 default 作为租户 ID，并同时提供 baseUrl 和 apiIndicator 配置。

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

const logtoEndpoint = 'https://your.logto.endpoint'; // 替换为你的 Logto endpoint
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 用户：当你与 Logto Management API 交互时，不能使用自定义域名，请使用默认的 Logto endpoint https://{your_tenant_id}.logto.app/oidc/token 获取访问令牌 (Access 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。

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'

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

警告:

访问令牌 (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

Node.js 使用 `@logto/api` SDK
Node.js
cURL

使用 @logto/api SDK，你可以直接与任何 Management API 交互，参考下面的代码片段。访问令牌 (Access token) 会在内部缓存，并在需要时自动刷新。

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

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

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

const logtoEndpoint = 'https://your.logto.endpoint'; // 替换为你的 Logto endpoint
const accessToken = 'eyJhb...2g'; // 访问令牌 (Access token)

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

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

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

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

请记得将实际值替换为你自己的。Bearer 后面的值应为你收到的访问令牌 (Access token)（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 headers

分页响应头示例如下：

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)

什么是 Logto Management API？​

如何访问 Logto Management API​

创建 M2M 应用​

获取访问令牌 (Access token)​

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

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

Logto Cloud​

自托管 / OSS​

访问令牌 (Access token) 响应​

访问令牌 (Access token) 响应​

使用访问令牌 (Access token) 访问 Logto Management API​

使用 Logto Management API 的典型场景​

自主实现用户资料页​

高级用户搜索​

自主实现组织管理​

使用 Logto Management API 的小贴士​

管理分页 API 响应​

使用 link headers​

使用 total-number header​

更改页码和每页数量​

速率限制​

相关资源​

什么是 Logto Management API？

如何访问 Logto Management API

创建 M2M 应用

获取访问令牌 (Access token)

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

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

Logto Cloud

自托管 / OSS

访问令牌 (Access token) 响应

访问令牌 (Access token) 响应

使用访问令牌 (Access token) 访问 Logto Management API

使用 Logto Management API 的典型场景

自主实现用户资料页

高级用户搜索

自主实现组织管理

使用 Logto Management API 的小贴士

管理分页 API 响应

使用 link headers

使用 total-number header

更改页码和每页数量

速率限制

相关资源