跳到主要内容

通过 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 开关即可开启。

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

  1. 安全字段
    • 包括:主邮箱、主手机号、社交身份、密码和 MFA。
    • 终端用户在编辑这些字段前,必须通过密码、邮箱或短信验证身份,获取一个 10 分钟有效的验证记录 ID。详见 获取验证记录 ID
    • 若要使用 WebAuthn 密钥作为 MFA,请将你的前端应用域名添加到 WebAuthn 相关来源,以便账户中心和登录体验共享密钥。详见 绑定新的 WebAuthn 密钥
  2. 资料字段
    • 包括:用户名、姓名、头像、profile(其他标准资料属性)和 自定义数据
    • 终端用户可直接编辑这些字段,无需额外验证。
  3. 密钥库:对于 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>'
备注:

请先 启用 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>'
备注:

请先 启用 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