通过 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(其他标准资料属性)和 custom data。
- 终端用户可直接编辑,无需额外验证。
- 密钥库:
- 对于 OIDC 或 OAuth 社交和企业连接器,Logto 密钥库 会在认证后安全存储第三方访问令牌 (Access token) 和刷新令牌 (Refresh token)。应用可调用外部 API,如同步 Google 日历事件,无需再次提示用户登录。启用 Account API 后,令牌检索功能自动开放。
- 会话管理:
- 启用后,用户可查看和管理活跃会话,包括设备信息和上次登录时间。用户还可撤销会话,实现特定设备登出。
- 终端用户访问会话管理前,需通过密码、邮箱或短信验证身份,获取一个 10 分钟有效的验证记录 ID。详见 获取验证记录 ID。
如何访问 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, // 管理用户资料
UserScope.Sessions, // 管理用户会话
],
};
获取访问令牌 (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": "..."
}
通过发送验证码到用户邮箱或手机号验证
以邮箱为例,请求新的验证码并获取验证记录 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":"..."}'
与注册时设置的密码一样,通过 Account API 设置的密码也必须符合你在 控制台 > 安全 > 密码策略 配置的 密码策略。如不符合策略,Logto 会返回详细的校验结果和错误信息。
更新或绑定新邮箱
使用此方法需先 配置邮箱连接器,并确保已配置 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 放入请求体。
此请求需要两个独立的验证记录 ID:
logto-verification-id(请求头):证明用户身份,用于敏感操作前。可通过 验证用户密码 或 发送验证码到现有邮箱或手机号 获得。newIdentifierVerificationRecordId(请求体):证明对新邮箱的所有权。即上文POST /api/verifications/verification-code返回的verificationRecordId。
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_from_existing_identifier>' \
-H 'content-type: application/json' \
# "newIdentifierVerificationRecordId" 证明新邮箱所有权(来自上方验证码流程)
--data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'
与注册时收集的邮箱一样,通过 Account API 绑定的邮箱也必须通过你在 控制台 > 安全 > 黑名单 配置的 黑名单 校验。如邮箱违反策略,Logto 会拒绝请求并返回详细错误。
移除用户邮箱
要移除用户邮箱,可使用 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 请求授权 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 字段值。
最后,可使用 POST /api/my-account/identities 绑定社交账号。
此请求需要两个独立的验证记录 ID:
logto-verification-id(请求头):证明用户身份,用于敏感操作前。可通过 验证用户密码 或 发送验证码到现有邮箱或手机号 获得。newIdentifierVerificationRecordId(请求体):标识要绑定的社交身份。即上文POST /api/verifications/social返回的verificationRecordId。
curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
-H 'authorization: Bearer <access_token>' \
# 验证用户身份(来自密码或现有邮箱/手机号验证)
-H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
-H 'content-type: application/json' \
# "newIdentifierVerificationRecordId" 标识要绑定的社交账号(来自上方社交验证流程)
--data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'
移除社交账号
要移除社交账号,可使用 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 字段。
步骤 1:将前端应用域名添加到相关来源
WebAuthn 密钥绑定到特定主机名(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"]}'
WebAuthn 最多支持 5 个唯一 eTLD+1 标签作为相关来源。eTLD+1(有效顶级域加一标签)为可注册域部分。例如:
https://example.com、https://app.example.com、https://auth.example.com计为 一个 标签(example.com)https://shopping.com、https://shopping.co.uk、https://shopping.co.jp也计为 一个 标签(shopping)https://example.com和https://another.com计为 两个 标签
如需支持超过 5 个不同域名作为相关来源,请参考 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, // 第一步服务器返回的数据
});
// 保存 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:第二步本地浏览器返回的响应。verificationRecordId:第一步服务器返回的验证记录 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:第一步服务器返回的验证记录 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:user@example.com?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:第一步生成的 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。
管理用户会话
列出活跃会话
要列出用户活跃会话,可使用 GET /api/my-account/sessions 接口。
- 访问此接口需配置
UserScope.Sessions权限。 - 账户中心设置中的
Sessions字段需设为只读或可编辑。
curl https://[tenant-id].logto.app/api/my-account/sessions \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json'
按会话 ID 撤销会话
要撤销指定会话,使用 DELETE /api/my-account/sessions/{sessionId} 接口。
- 访问此接口需配置
UserScope.Sessions权限。 - 账户中心设置中的
Sessions字段需设为可编辑。
curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json'
可选查询参数:
revokeGrantsTarget:可选,指定撤销会话时要撤销的授权目标。可选值:all:撤销与该会话关联的所有授权。firstParty:仅撤销与该会话关联的第一方应用授权(推荐大多数场景,既撤销自有应用访问,又保留第三方应用授权,提升用户体验)。- 未指定:默认行为为撤销未包含
offline_access权限的授权,通常意味着撤销该会话的非刷新令牌授权。