透過 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 Passkey 作為 MFA，請將前端應用程式網域加入 WebAuthn 相關來源，讓帳號中心與登入體驗可共用 Passkey。詳見連結新 WebAuthn Passkey。
個人資料欄位：
- 包含：使用者名稱、姓名、大頭貼、profile（其他標準個人資料屬性）、自訂資料。
- 終端使用者可直接編輯，無需額外驗證。
密鑰保管庫 (Secret vault)：針對 OIDC 或 OAuth 社交與企業連接器，Logto 密鑰保管庫會在驗證後安全儲存第三方存取權杖 (Access token) 與重新整理權杖 (Refresh token)。應用程式可直接呼叫外部 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: [
    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 互動時，請將存取權杖 (Access token) 以 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 發送請求

更新使用者識別資訊時，請在請求標頭加上 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，請妥善保存。

使用者授權後，會收到帶有 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 端點連結社交帳號。

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 Passkey

備註:

請先啟用 MFA 與 WebAuthn。

備註:

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

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

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

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

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 端點請求註冊新 Passkey。Logto 允許每個帳號註冊多組 Passkey。

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：於本地瀏覽器註冊 Passkey

以 @simplewebauthn/browser 為例，可用 startRegistration 於本地瀏覽器註冊 Passkey。

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // 步驟 1 伺服器回傳資料
});
// 儲存 response 以供後續使用

步驟 4：驗證 Passkey 註冊

使用 POST /api/verifications/web-authn/registration/verify 端點驗證 Passkey 註冊。

此步驟會驗證驗證器產生的加密簽章，確保 Passkey 合法產生且傳輸過程未被竄改。

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：連結 Passkey

最後，使用 POST /api/my-account/mfa-verifications 端點將 Passkey 連結至使用者帳號。

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 Passkey

管理現有 WebAuthn Passkey 可使用 GET /api/my-account/mfa-verifications 端點取得目前 Passkey 與其他 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 Passkey 為 WebAuthn
name：Passkey 名稱，選填
agent：Passkey 的使用者代理資訊

更新 Passkey 名稱可使用 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":"..."}'

刪除 Passkey 則使用 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 錯誤。

管理備用驗證碼 (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 Passkey​

管理現有 WebAuthn Passkey​

連結新 TOTP​

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

什麼是 Logto Account API

如何啟用 Account API

如何存取 Account API

取得存取權杖 (Access token)

使用存取權杖存取 Account API

管理基本帳號資訊

取得使用者帳號資訊

更新基本帳號資訊

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

取得驗證紀錄 ID

驗證使用者密碼

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

夾帶驗證紀錄 ID 發送請求

更新使用者密碼

更新或連結新電子郵件

移除使用者電子郵件

管理手機

連結新社交帳號

移除社交帳號

連結新 WebAuthn Passkey

管理現有 WebAuthn Passkey

連結新 TOTP

管理備用驗證碼 (Backup codes)