与 Management API 交互
什么是 Logto Management API?
Logto Management API 是一套全面的 API,开发者可以通过它们完全控制实现,以满足产品需求和技术栈。它是预构建的,列在 控制台 > API 资源 > Logto Management API 中,不能删除或修改。
其标识符的格式为 https://[tenant-id].logto.app/api
通过 Logto Management API,你可以访问 Logto 强大的后端服务,这些服务具有高度的可扩展性,可以在多种场景中使用。它超越了管理控制台的低代码能力。
以下是一些常用的 API:
要了解更多可用的 API,请访问 https://openapi.logto.io/。
如何访问 Logto Management API
创建一个 M2M 应用
如果你不熟悉 M2M(机器对机器)认证 (Authentication) 流程,我们建议先阅读 理解认证 (Authentication) 流程 以了解基本概念。
前往 控制台 > 应用程序,选择“机器对机器”应用程序类型并开始创建过程。
在创建 M2M 应用程序的过程中,你将被引导到一个页面,在那里你可以为你的应用程序分配 M2M 角色:
或者,当你已经创建了一个 M2M 应用程序时,你也可以在 M2M 应用程序详情页面上分配这些角色:
在角色 (Role) 分配模块中,你可以看到所有 M2M 角色 (Roles) 都被包含在内,带有 Logto 图标的角色 (Roles) 表示这些角色 (Roles) 包含 Logto Management API 权限。
现在为你的 M2M 应用分配包含 Logto Management API 权限的 M2M 角色 (Roles)。
获取访问令牌 (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:
获取 Logto Management API 的访问令牌 (Access token)
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) 响应
成功的访问响应体如下:
{
"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 中的所有应用:
- 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:分步指南
使用 Postman 在几分钟内获取 M2M 访问令牌