跳到主要内容

通过 Account API 进行账户设置

什么是 Logto Account API​

Logto Account API 是一套全面的 API，允许终端用户直接通过 API 访问，无需经过 Management API，主要亮点如下：

  • 直接访问：Account API 让终端用户可以直接访问和管理自己的账户资料，无需通过 Management API 中转。
  • 用户资料与身份管理：用户可以完全管理自己的资料和安全设置，包括更新邮箱、手机号、密码等身份信息，以及管理社交连接。MFA 和 SSO 支持即将上线。
  • 全局访问控制：管理员拥有对访问设置的完全全局控制，可以自定义每个字段。
  • 无缝授权 (Authorization)：授权 (Authorization) 变得前所未有的简单！只需使用 client.getAccessToken() 获取 OP (Logto) 的不透明令牌 (Opaque token)，并将其作为 Bearer <access_token> 附加到 Authorization 头部即可。

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

常见的使用场景包括：

  • 获取用户资料
  • 更新用户资料
  • 更新用户密码
  • 更新用户身份信息，包括邮箱、手机号和社交连接

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

备注:

以下设置的专用 Account API 即将上线：MFA、SSO、自定义数据（用户）、账户删除。在此期间，你可以使用 Logto Management API 实现这些功能。详见 通过 Management API 进行账户设置。

如何启用 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：社交连接。

更多 API 详情请参见 Logto Management API Reference。

如何访问 Account API​

获取访问令牌 (Access token)​

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

如果你没有使用官方 SDK，则应在访问令牌 (Access token) 授权请求 /oidc/token 时将 resource 设为空。

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

在与 Account API 交互时，应将访问令牌 (Access token) 以 Bearer 格式（Bearer YOUR_TOKEN）放在 HTTP 头部的 Authorization 字段中。

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

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 对涉及标识符及其他敏感信息的操作需要额外一层授权 (Authorization)。

获取验证记录 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 POST 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 发送请求​

在发送更新用户标识符的请求时，需要在请求头中通过 logto-verification-id 字段附加验证记录 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 POST 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 端点移除用户手机号。

要绑定新的社交连接，首先需要请求授权 (Authorization) 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：用户授权 (Authorization) 应用后跳转的 URI，你需要在此 URL 上托管网页并捕获回调。
  • state：用户授权 (Authorization) 应用后返回的 state，是用于防止 CSRF 攻击的随机字符串。

响应中会有一个 verificationRecordId，请妥善保存以备后用。

用户授权 (Authorization) 应用后，你会在 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 是用户授权 (Authorization) 应用后社交连接器返回的数据，你需要在回调页面解析并获取 redirectUri 的查询参数，并将其封装为 JSON 作为 connectorData 字段的值。

最后，可以使用 POST /api/my-account/identities 端点绑定社交连接。

curl -X POST 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>'