通过 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 密钥。
- 资料字段:
- 密钥库:对于 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": "..."
}
通过发送验证码到用户邮箱或手机号进行验证
以邮箱为例,请求新的验证码并获取验证记录 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
字段。
步骤 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
。