跳到主要内容

通过 Account API 设置账户

什么是 Logto Account API​

Logto Account API 是一组全面的 API，允许终端用户直接访问 API，而无需通过 Management API。以下是其亮点：

  • 直接访问：Account API 使终端用户能够直接访问和管理自己的账户资料，而无需中转 Management API。
  • 用户资料和身份管理：用户可以完全管理他们的资料和安全设置，包括更新电子邮件、电话和密码等身份信息，以及管理社交连接。MFA 和 SSO 支持即将推出。
  • 全局访问控制：管理员对访问设置拥有完全的全局控制，可以自定义每个字段。
  • 无缝授权：授权比以往更简单！只需使用 client.getAccessToken() 获取一个用于 OP (Logto) 的不透明访问令牌，并将其作为 Bearer <access_token> 附加到授权头中。

通过 Logto Account API，你可以构建一个自定义的账户管理系统，如完全集成 Logto 的个人资料页面。

以下是一些常见的用法：

  • 检索用户资料
  • 更新用户资料
  • 更新用户密码
  • 更新用户身份信息，包括电子邮件、电话和社交连接

要了解更多可用的 API，请访问 Logto Account API Reference 和 Logto Verification API Reference。

如何启用 Account API​

默认情况下，Account API 是禁用的。要启用它，你需要使用 Management API 更新全局设置。

API 端点 /api/account-center 可用于检索和更新账户中心设置，你可以使用它来启用或禁用 Account API，并自定义字段。

示例请求：

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

enabled 字段用于启用或禁用 Account API，而 fields 字段用于自定义字段，值可以是 Off、Edit、ReadOnly。默认值是 Off。字段列表：

  • name：名称字段。
  • avatar：头像字段。
  • profile：资料字段，包括其子字段。
  • username：用户名字段。
  • email：电子邮件字段。
  • phone：电话字段。
  • password：密码字段，当获取时，如果用户已设置密码，则返回 true，否则返回 false。
  • social：社交连接。

在 Logto Management API Reference 中了解更多 API 详细信息。

如何访问 Account API​

获取访问令牌​

在你的应用程序中设置 SDK 后，你可以使用 client.getAccessToken() 方法获取访问令牌。此令牌是不透明令牌，可用于访问 Account API。

如果你没有使用官方 SDK，你应该在访问令牌授予请求 /oidc/token 中将 resource 设置为空。

使用访问令牌访问 Account API​

在与 Account API 交互时，你应该将访问令牌放在 HTTP 头的 Authorization 字段中，格式为 Bearer (Bearer YOUR_TOKEN)。

获取用户账户信息的示例：

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

管理基本账户信息​

检索用户账户信息​

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

响应体如下：

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

响应字段可能会根据账户中心设置而有所不同。

更新基本账户信息​

基本账户信息包括用户名、名称、头像和资料。

要更新用户名、名称和头像，你可以使用 PATCH /api/my-account 端点。

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

要更新资料，你可以使用 PATCH /api/my-account/profile 端点。

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

管理标识符和其他敏感信息​

出于安全原因，Account API 需要对涉及标识符和其他敏感信息的操作进行另一层授权。

获取验证记录 ID​

首先，你需要获取一个验证记录 ID，这可以用于在更新标识符时验证用户的身份。

要获取验证记录 ID，你可以验证用户的密码或向用户的电子邮件或电话发送验证码。

验证用户的密码​

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

响应体如下：

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

通过向用户的电子邮件或电话发送验证码进行验证​

备注:

要使用此方法，你需要 配置电子邮件连接器 或 SMS 连接器，并确保配置了 UserPermissionValidation 模板。

以电子邮件为例，请求新的验证码并获取验证记录 ID：

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

响应体如下：

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

收到验证码后，你可以使用它来更新验证记录的验证状态。

curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

在验证代码后，你现在可以使用验证记录 ID 更新用户的标识符。

使用验证记录 ID 发送请求​

在发送请求以更新用户的标识符时，你需要将验证记录 ID 附加到请求头中的 logto-verification-id 字段。

更新或链接新电子邮件​

备注:

要使用此方法，你需要 配置电子邮件连接器，并确保配置了 BindNewIdentifier 模板。

要更新或链接新电子邮件，你首先需要证明电子邮件的所有权。

调用 POST /api/verifications/verification-code 端点请求验证码。

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

你将在响应中找到一个 verificationId，并在电子邮件中收到验证码，使用它来验证电子邮件。

curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

在验证代码后，你现在可以更新用户的电子邮件，将 verificationId 设置为请求体中的 newIdentifierVerificationRecordId。

curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'

移除用户的电子邮件​

要移除用户的电子邮件，你可以使用 DELETE /api/my-account/primary-email 端点。

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

管理电话​

备注:

要使用此方法，你需要 配置 SMS 连接器，并确保配置了 BindNewIdentifier 模板。

类似于更新电子邮件，你可以使用 PATCH /api/my-account/primary-phone 端点更新或链接新电话。并使用 DELETE /api/my-account/primary-phone 端点移除用户的电话。

链接新的社交连接​

要链接新的社交连接，首先你应该请求一个授权 URL：

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'
  • connectorId：社交连接器 的 ID。
  • redirectUri：用户授权应用程序后的重定向 URI，你应该在此 URL 上托管一个网页并捕获回调。
  • state：用户授权应用程序后返回的状态，它是一个随机字符串，用于防止 CSRF 攻击。

在响应中，你会找到一个 verificationRecordId，请保存以备后用。

在用户授权应用程序后，你将在 redirectUri 上收到带有 state 参数的回调。然后你可以使用 POST /api/verifications/social/verify 端点验证社交连接。

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

connectorData 是用户授权应用程序后社交连接器返回的数据，你需要在回调页面中解析并获取 redirectUri 的查询参数，并将其包装为 JSON 作为 connectorData 字段的值。

最后，你可以使用 PATCH /api/my-account/identities 端点链接社交连接。

curl -X PATCH https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"newIdentifierVerificationRecordId":"..."}'

移除社交连接​

要移除社交连接，你可以使用 DELETE /api/my-account/identities 端点。

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'