通过 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 头部即可。

备注:

为确保访问令牌 (Access token) 具有适当的权限，请确保你已在 Logto 配置中正确配置了相应的权限 (Scopes)。

例如，POST /api/my-account/primary-email API 需要配置 email 权限 (Scope)；POST /api/my-account/primary-phone API 需要配置 phone 权限 (Scope)。

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...其他选项
  // 添加适合你用例的权限 (Scopes)。
  scopes: [
    UserScope.Email, // 用于 `{POST,DELETE} /api/my-account/primary-email` API
    UserScope.Phone, // 用于 `{POST,DELETE} /api/my-account/primary-phone` API
    UserScope.CustomData, // 管理自定义数据
    UserScope.Address, // 管理地址
    UserScope.Identities, // 用于身份和 MFA 相关 API
    UserScope.Profile, // 管理用户资料
  ],
};

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

常见用例如下：

获取用户资料
更新用户资料
更新用户密码
更新用户身份信息，包括邮箱、手机号和社交连接
管理 MFA 因子（验证）

想了解更多可用 API，请访问 Logto Account API 参考文档和 Logto Verification API 参考文档。

备注:

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

MFA 管理 API（TOTP 和备份码）目前正在开发中，仅在 isDevFeaturesEnabled 标志设置为 true 时可用。WebAuthn 密钥管理已全面开放。

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

更多 API 详情请参见 Logto Management API 参考文档。

如何访问 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 交互时，应在 HTTP 头部的 Authorization 字段中以 Bearer 格式（Bearer YOUR_TOKEN）包含访问令牌 (Access 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 对涉及标识符和其他敏感信息的操作需要额外的授权 (Authorization) 层。

获取验证记录 ID

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

要获取验证记录 ID，可以验证用户密码，或向用户邮箱或手机号发送验证码。

想了解更多关于验证的信息，请参见通过 Account API 进行安全验证。

验证用户密码

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。

更新用户密码

要更新用户密码，可以使用 POST /api/my-account/password 端点。

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

更新或绑定新邮箱

备注:

要使用此方法，你需要配置邮箱连接器，并确保已配置 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 POST 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>'

绑定新的 WebAuthn 密钥

备注:

记得先启用 MFA 和 WebAuthn。

备注:

要使用此方法，你需要在账户中心设置中启用 mfa 字段。

第 0 步：将你的前端应用 origin 添加到相关 origin 列表。

浏览器中的密钥（Passkey）与特定主机名（RP ID）绑定，只有 RP ID 的 origin 才能注册或验证密钥。但你的前端应用请求 Account API 时的 origin 与 Logto 登录页不同，因此需要将前端应用 origin 添加到相关 origin 列表。这样你的前端应用就可以在其他 RP ID 下注册和验证密钥。

默认情况下，Logto 会将 RP ID 设置为租户域名，例如租户域名为 https://example.logto.app，RP ID 就是 example.logto.app。如果你使用自定义域名，RP ID 就是自定义域名，例如 https://auth.example.com，RP ID 就是 auth.example.com。

现在，将你的前端应用 origin 添加到相关 origin，例如前端应用 origin 为 https://account.example.com：

curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

想了解更多相关 origin，请参考 Related Origin Requests 文档。

第 1 步：请求新的注册选项。

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

你会收到如下响应：

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

第 2 步：在本地浏览器注册密钥。

以 @simplewebauthn/browser 为例，可以用 startRegistration 方法在本地浏览器注册密钥。

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // 第 1 步服务器返回的数据
});
// 保存 response 以备后用

第 3 步：验证密钥。

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

payload：第 2 步本地浏览器返回的响应。
verificationRecordId：第 1 步服务器返回的验证记录 ID。

第 4 步：最后，绑定密钥。

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

verification_record_id：有效的验证记录 ID，通过验证用户现有因子获得，详见获取验证记录 ID。
type：MFA 因子类型，目前仅支持 WebAuthn。
newIdentifierVerificationRecordId：第 1 步服务器返回的验证记录 ID。

管理已有 WebAuthn 密钥

要管理已有 WebAuthn 密钥，可以使用 GET /api/my-account/mfa-verifications 端点获取当前密钥和其他 MFA 验证因子。

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

响应体示例：

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id：验证因子的 ID。
type：验证因子类型，WebAuthn 密钥为 WebAuthn。
name：密钥名称，可选字段。
agent：密钥的 user agent。

更新密钥名称：

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

删除密钥：

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

绑定新的 TOTP

备注:

记得先启用 MFA 和 TOTP。

备注:

要使用此方法，你需要在账户中心设置中启用 mfa 字段。

第 1 步：生成 TOTP 密钥。

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

响应体示例：

{
  "secret": "..."
}

第 2 步：向用户展示 TOTP 密钥。

使用该密钥生成二维码或直接展示给用户。用户应将其添加到自己的身份验证器应用（如 Google Authenticator、Microsoft Authenticator 或 Authy）。

二维码的 URI 格式为：

otpauth://totp/[发行者 (Issuer)]:[账户]?secret=[密钥 (Secret)]&issuer=[发行者 (Issuer)]

示例：

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

第 3 步：绑定 TOTP 因子。

用户将密钥添加到身份验证器应用后，需要验证并绑定到账户：

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

verification_record_id：有效的验证记录 ID，通过验证用户现有因子获得，详见获取验证记录 ID。
type：必须为 Totp。
secret：第 1 步生成的 TOTP 密钥。

备注:

一个用户同一时间只能有一个 TOTP 因子。如果用户已存在 TOTP 因子，再添加会返回 422 错误。

管理备份码

备注:

记得先启用 MFA 和备份码。

备注:

要使用此方法，你需要在账户中心设置中启用 mfa 字段。

第 1 步：生成新的备份码：

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

响应体示例：

{
  "codes": ["...", "...", "..."]
}

第 2 步：向用户展示备份码：

important:

在将备份码绑定到用户账户前，必须向用户展示这些备份码，并提示他们：

立即下载或抄写这些备份码
将其存放在安全的位置
每个备份码只能使用一次
这些备份码是他们丢失主 MFA 方法后最后的救命稻草

你应以清晰、易于复制的格式展示这些备份码，并考虑提供下载选项（如文本文件或 PDF）。

第 3 步：将备份码绑定到用户账户：

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

verification_record_id：有效的验证记录 ID，通过验证用户现有因子获得，详见获取验证记录 ID。
type：必须为 BackupCode。
codes：上一步生成的备份码数组。

备注:

一个用户同一时间只能有一组备份码。如果所有备份码都已用完，用户需要重新生成并绑定新备份码。
备份码不能作为唯一的 MFA 因子。用户必须至少启用一个其他 MFA 因子（如 WebAuthn 或 TOTP）。
每个备份码只能使用一次。

查看已有备份码：

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

响应体示例：

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code：备份码。
usedAt：该备份码被使用的时间戳，未使用时为 null。

什么是 Logto Account API​

如何启用 Account API​

如何访问 Account API​

获取访问令牌 (Access token)​

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

管理基础账户信息​

获取用户账户信息​

更新基础账户信息​

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

获取验证记录 ID​

验证用户密码​

通过向用户邮箱或手机号发送验证码进行验证​

携带验证记录 ID 发送请求​

更新用户密码​

更新或绑定新邮箱​

移除用户邮箱​

管理手机号​

绑定新的社交连接​

移除社交连接​

绑定新的 WebAuthn 密钥​

管理已有 WebAuthn 密钥​

绑定新的 TOTP​

管理备份码​

什么是 Logto Account API

如何启用 Account API

如何访问 Account API

获取访问令牌 (Access token)

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

管理基础账户信息

获取用户账户信息

更新基础账户信息

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

获取验证记录 ID

验证用户密码

通过向用户邮箱或手机号发送验证码进行验证

携带验证记录 ID 发送请求

更新用户密码

更新或绑定新邮箱

移除用户邮箱

管理手机号

绑定新的社交连接

移除社交连接

绑定新的 WebAuthn 密钥

管理已有 WebAuthn 密钥

绑定新的 TOTP

管理备份码