通过 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 完全集成的自定义账户管理系统，比如个人资料页。

常见的使用场景包括：

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

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

备注:

SSO 账户查看和账户删除功能目前通过 Logto Management API 提供。具体实现细节请参见通过 Management API 进行账户设置。

如何启用 Account API

进入控制台 > 登录与账户 > 账户中心。

Account API 默认关闭，因此其访问控制是锁定的。切换 启用 Account API 开关即可开启。

启用后，你可以为标识符、资料数据和第三方令牌访问配置每个字段的权限。每个字段支持 关闭、只读 或 可编辑，默认是 关闭。

安全字段：
- 包括：主邮箱、主手机号、社交身份、密码和 MFA。
- 终端用户在编辑这些字段前，必须通过密码、邮箱或短信验证身份，获取一个 10 分钟有效的验证记录 ID。详见获取验证记录 ID。
- 若要使用 WebAuthn 密钥作为 MFA，请将你的前端应用域名添加到 WebAuthn 相关来源，以便账户中心和登录体验共享密钥。详见绑定新的 WebAuthn 密钥。
资料字段：
- 包括：用户名、姓名、头像、profile（其他标准资料属性）和自定义数据。
- 终端用户可直接编辑这些字段，无需额外验证。
密钥库：对于 OIDC 或 OAuth 社交和企业连接器，Logto 密钥库会在认证后安全存储第三方访问令牌和刷新令牌。应用可调用外部 API（如同步 Google 日历事件），无需再次提示用户登录。启用 Account API 后，令牌获取功能会自动开放。

如何访问 Account API

备注:

为确保访问令牌 (Access token) 拥有相应权限，请在 Logto 配置中正确设置对应的权限 (Scopes)。

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

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, // 管理用户资料
  ],
};

获取访问令牌 (Access token)

在应用中配置好 SDK 后，可以使用 client.getAccessToken() 方法获取访问令牌 (Access token)。该令牌是不透明令牌 (Opaque token)，可用于访问 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>'

管理基础账户信息

获取用户账户信息

要获取用户数据，可调用 GET /api/my-account 接口。

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

响应体示例：

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

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

更新基础账户信息

基础账户信息包括用户名、姓名、头像、自定义数据及其他资料信息。

要更新 用户名、姓名、头像和 customData，可调用 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":"..."}'

要更新其他资料信息，包括 familyName、givenName、middleName、nickname、profile（个人主页 URL）、website、gender、birthdate、zoneinfo、locale 和 address，可调用 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，有效期为 10 分钟（TTL）。该 ID 可用于在更新敏感信息前验证用户身份。即用户通过密码、邮箱验证码或短信验证码验证身份后，有 10 分钟时间可更新与认证 (Authentication) 相关的数据，包括标识符、凭证、社交账号绑定和 MFA。

获取验证记录 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": "..."
}

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

备注:

使用此方法需先配置邮箱连接器或配置短信连接器，并确保已配置 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 更新用户标识符。

想了解更多验证相关内容，请参见通过 Account API 进行安全验证。

携带验证记录 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":"..."}'

验证通过后，可调用 PATCH /api/my-account/primary-email 更新用户邮箱，将 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>'

管理手机号

备注:

使用此方法需先配置短信连接器，并确保已配置 BindNewIdentifier 模板。

与更新邮箱类似，可通过 PATCH /api/my-account/primary-phone 接口更新或绑定新手机号。通过 DELETE /api/my-account/primary-phone 接口移除用户手机号。

要绑定新的社交账号，首先需通过 POST /api/verifications/social 请求授权 (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：用户授权应用后跳转的 URI，你需要在此 URL 上托管网页并捕获回调。
state：用户授权应用后返回的 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 字段的值。

最后，可通过 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 字段。

步骤 1：将前端应用的域名添加到相关来源

WebAuthn 密钥绑定到特定主机名（即 Relying Party ID (RP ID)）。只有托管在 RP ID 来源的应用才能注册或认证 (Authentication) 这些密钥。

由于你的前端应用与 Logto 认证 (Authentication) 页面不在同一域名下，需配置 相关来源 以允许跨域密钥操作。

Logto 如何确定 RP ID：

默认设置：仅使用 Logto 默认域名 https://[tenant-id].logto.app 时，RP ID 为 [tenant-id].logto.app
自定义域名：如配置了自定义域名 https://auth.example.com，RP ID 则为 auth.example.com

配置相关来源：

通过 PATCH /api/account-center 接口添加前端应用的来源。例如，账户中心运行在 https://account.example.com：

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

更多相关来源说明，请参考 Related Origin Requests 文档。

步骤 2：请求新的注册选项

通过 POST /api/verifications/web-authn/registration 接口请求注册新密钥。Logto 允许每个账户注册多个密钥。

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": "..."
}

步骤 3：在本地浏览器注册密钥

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

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

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

步骤 4：验证密钥注册

通过 POST /api/verifications/web-authn/registration/verify 接口验证密钥注册。

此步骤会验证认证器生成的加密签名，确保密钥合法创建且传输过程中未被篡改。

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。

步骤 5：绑定密钥

最后，可通过 POST /api/my-account/mfa-verifications 接口将密钥绑定到用户账户。

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。

通过 PATCH /api/my-account/mfa-verifications/{verificationId}/name 更新密钥名称：

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":"..."}'

通过 DELETE /api/my-account/mfa-verifications/{verificationId} 删除密钥：

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 密钥

通过 POST /api/my-account/mfa-verifications/totp-secret/generate 接口生成 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]:[Account]?secret=[Secret]&issuer=[Issuer]

示例：

otpauth://totp/YourApp:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

步骤 3：绑定 TOTP 因子

用户将密钥添加到认证器应用后，需要验证并绑定到账户。通过 POST /api/my-account/mfa-verifications 绑定 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：生成新备份码

通过 POST /api/my-account/mfa-verifications/backup-codes/generate 接口生成一组新的 10 个备份码。

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：向用户展示备份码

在将备份码绑定到用户账户前，必须展示给用户，并提示：

立即下载或抄写这些备份码
妥善保管在安全的地方
每个备份码只能使用一次
这些码是丢失主 MFA 方法后的最后救援手段

建议以清晰、易复制的格式展示，并提供下载选项（如文本文件或 PDF）。

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

通过 POST /api/my-account/mfa-verifications 绑定备份码到用户账户。

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）。
每个备份码只能使用一次。

查看已有备份码

要查看已有备份码及其使用状态，可通过 GET /api/my-account/mfa-verifications/backup-codes 接口：

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)​

使用访问令牌访问 Account API​

管理基础账户信息​

获取用户账户信息​

更新基础账户信息​

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

获取验证记录 ID​

验证用户密码​

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

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

更新用户密码​

更新或绑定新邮箱​

移除用户邮箱​

管理手机号​

绑定新的社交账号​

移除社交账号​

绑定新的 WebAuthn 密钥​

管理已有 WebAuthn 密钥​

绑定新的 TOTP​

管理备份码​

什么是 Logto Account API

如何启用 Account API

如何访问 Account API

获取访问令牌 (Access token)

使用访问令牌访问 Account API

管理基础账户信息

获取用户账户信息

更新基础账户信息

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

获取验证记录 ID

验证用户密码

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

携带验证记录 ID 发送请求

更新用户密码

更新或绑定新邮箱

移除用户邮箱

管理手机号

绑定新的社交账号

移除社交账号

绑定新的 WebAuthn 密钥

管理已有 WebAuthn 密钥

绑定新的 TOTP

管理备份码