透過 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 Reference 與 Logto Verification API Reference。

備註:

SSO 帳號檢視與帳號刪除功能目前僅能透過 Logto Management API 使用。詳見透過 Management API 管理帳號設定。

如何啟用 Account API

前往 Console > 登入與帳號 > 帳號中心。

Account API 預設為關閉，因此其存取控制設定為鎖定。切換 啟用 Account API 以開啟功能。

啟用後，可針對識別資訊、個人資料、第三方權杖存取等欄位設定權限。每個欄位支援 Off、ReadOnly 或 Edit，預設為 Off。

安全性欄位：
- 包含：主要電子郵件、主要手機、社交身分、密碼、MFA。
- 終端使用者編輯這些欄位前，必須先透過密碼、電子郵件或簡訊驗證身分，取得 10 分鐘有效的驗證紀錄 ID。詳見取得驗證紀錄 ID。
- 若要使用 WebAuthn 金鑰作為 MFA，請將前端應用程式網域加入 WebAuthn 相關來源，以便帳號中心與登入體驗共用金鑰。詳見連結新 WebAuthn 金鑰。
個人資料欄位：
- 包含：使用者名稱、姓名、大頭貼、profile（其他標準個人屬性）、custom data。
- 終端使用者可直接編輯，無需額外驗證。
密鑰保管庫 (Secret vault)：針對 OIDC 或 OAuth 社交與企業連接器，Logto 密鑰保管庫會在驗證後安全儲存第三方存取權杖與重新整理權杖。應用程式可直接呼叫外部 API（如同步 Google Calendar 事件），無需再次提示使用者登入。啟用 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: [
    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() 方法取得存取權杖。此權杖為不透明權杖 (Opaque token)，可用於存取 Account API。

若未使用官方 SDK，請將存取權杖請求 /oidc/token 的 resource 設為空。

使用存取權杖存取 Account API

與 Account API 互動時，請將存取權杖以 Bearer 格式（Bearer YOUR_TOKEN）放入 HTTP 標頭的 Authorization 欄位。

以下為取得使用者帳號資訊的範例：

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

回應欄位會依帳號中心設定而有所不同。

更新基本帳號資訊

基本帳號資訊包含使用者名稱、姓名、大頭貼、自訂資料及其他個人資料。

要更新 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（個人頁面網址）、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 針對涉及識別資訊與其他敏感資料的操作，需額外授權。

取得驗證紀錄 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 發送請求

更新使用者識別資訊時，請將驗證紀錄 ID 以 logto-verification-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 設定的密碼必須符合你在 Console > 安全性 > 密碼政策設定的密碼政策。若密碼不符政策，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:

此請求需兩組不同的驗證紀錄 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 連結的電子郵件必須通過你在 Console > 安全性 > 封鎖清單設定的封鎖清單驗證。若違反政策，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 取得授權網址。

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：使用者授權後的導向網址，需自行架設網頁並接收回呼。
state：授權後回傳的狀態，為隨機字串，用於防止 CSRF 攻擊。

回應中會有 verificationRecordId，請妥善保存。

使用者授權後，會收到帶有 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。

最後，可使用 POST /api/my-account/identities 端點連結社交帳號。

兩組不同的驗證紀錄 ID:

此請求需兩組不同的驗證紀錄 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 與 WebAuthn。

備註:

使用此方法前，需於帳號中心設定啟用 mfa 欄位。

步驟 1：將前端應用程式來源加入相關來源

WebAuthn 金鑰綁定於特定主機名稱（Relying Party ID, RP ID）。僅 RP ID 網域下的應用程式可註冊或驗證該金鑰。

由於前端應用程式與 Logto 驗證頁面網域不同，需設定 相關來源 以允許跨來源金鑰操作。

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：步驟 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：金鑰的使用者代理資訊。

更新金鑰名稱可使用 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 密鑰顯示給使用者

使用密鑰產生 QR code 或直接顯示給使用者，讓其加入驗證器 App（如 Google Authenticator、Microsoft Authenticator、Authy）。

QR code URI 格式如下：

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

範例：

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

步驟 3：綁定 TOTP 因子

使用者將密鑰加入驗證器 App 後，需驗證並綁定至帳號。使用 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 錯誤。

管理備用驗證碼 (Backup codes)

備註:

請先啟用 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​

管理備用驗證碼 (Backup codes)​

什麼是 Logto Account API

如何啟用 Account API

如何存取 Account API

取得存取權杖 (Access token)

使用存取權杖存取 Account API

管理基本帳號資訊

取得使用者帳號資訊

更新基本帳號資訊

管理識別資訊與其他敏感資料

取得驗證紀錄 ID

驗證使用者密碼

發送驗證碼至使用者電子郵件或手機

夾帶驗證紀錄 ID 發送請求

更新使用者密碼

更新或連結新電子郵件

移除使用者電子郵件

管理手機

連結新社交帳號

移除社交帳號

連結新 WebAuthn 金鑰

管理現有 WebAuthn 金鑰

連結新 TOTP

管理備用驗證碼 (Backup codes)