透過 Account API 管理帳戶設定

什麼是 Logto Account API

Logto Account API 是一組完整的 API，讓終端使用者可以直接透過 API 存取帳戶，而無需經過 Management API。重點如下：

直接存取：Account API 讓終端使用者能直接存取並管理自己的帳戶資料，無需透過 Management API 中繼。
使用者資料與身分管理：使用者可完整管理個人資料與安全設定，包括更新電子郵件、手機、密碼等身分資訊，以及管理社交連結。MFA 與 SSO 支援即將推出。
全域存取控制：管理員可對存取設定進行全域控制，並自訂每個欄位。
無縫授權 (Authorization)：授權 (Authorization) 更簡單！只需使用 client.getAccessToken() 取得 Logto 的不透明權杖 (Opaque token)，並以 Bearer <access_token> 附加於 Authorization 標頭即可。

備註:

為確保存取權杖 (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, // 管理使用者資料
  ],
};

透過 Logto Account API，你可以打造與 Logto 完整整合的自訂帳戶管理系統，例如個人資料頁面。

常見使用情境如下：

取得使用者資料
更新使用者資料
更新使用者密碼
更新使用者身分（包含電子郵件、手機、社交連結）
管理 MFA 因子（驗證）

想瞭解更多可用 API，請參閱 Logto Account API Reference 與 Logto Verification API Reference。

備註:

SSO 帳戶檢視與帳戶刪除功能目前僅能透過 Logto Management API 使用。實作細節請參考透過 Management API 管理帳戶設定。

如何啟用 Account API

預設情況下，Account API 為停用狀態。你需透過 Management API 更新全域設定來啟用。

API 端點 /api/account-center 可用於取得與更新帳戶中心設定。你可以用它來啟用 / 停用 Account API 並自訂欄位。

範例請求：

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

enabled 欄位用於啟用 / 停用 Account API，fields 欄位用於自訂欄位，值可為 Off、Edit、ReadOnly，預設為 Off。欄位列表如下：

name：名稱欄位。
avatar：頭像欄位。
profile：個人資料欄位，包含子欄位。
username：使用者名稱欄位。
email：電子郵件欄位。
phone：手機欄位。
password：密碼欄位，查詢時若使用者已設密碼則回傳 true，否則為 false。
social：社交連結。
mfa：MFA 因子。

更多 API 細節請參閱 Logto Management API Reference。

如何存取 Account API

取得存取權杖 (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 對涉及身分識別與敏感資訊的操作需額外授權 (Authorization) 驗證。

取得驗證紀錄 ID

首先，你需取得一組 驗證紀錄 ID，有效期為 10 分鐘（TTL）。此 ID 用於在更新敏感資訊前驗證使用者身分。也就是說，當使用者成功通過密碼、電子郵件驗證碼或簡訊驗證碼驗證後，有 10 分鐘可更新驗證相關資料（如身分、憑證、社交帳號連結、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 請求授權網址。

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，請妥善保存。

使用者授權後，你會在 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 的來源下運作的應用程式可註冊 / 驗證該通行密鑰。

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

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 密鑰顯示給使用者

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

QR code URI 格式如下：

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

範例：

otpauth://totp/YourApp:[email protected]?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 錯誤。

管理備用驗證碼

備註:

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

管理備用驗證碼