透過 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。

備註:

以下設定的專屬 Account API 即將推出：SSO、自訂資料（使用者）、帳號刪除。期間可透過 Logto Management API 實作，詳見透過 Management API 管理帳號設定。

MFA 管理 API（TOTP 與備用碼）目前開發中，僅於 isDevFeaturesEnabled 為 true 時可用。WebAuthn Passkey 管理已全面開放。

如何啟用 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 分鐘可更新驗證 (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 更新使用者電子郵件，並於請求主體帶入 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 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 因子，若已存在再新增會回傳 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 Passkey​

管理現有 WebAuthn Passkey​

綁定新 TOTP​

管理備用碼​

什麼是 Logto Account API

如何啟用 Account API

如何存取 Account API

取得存取權杖 (Access token)

使用存取權杖存取 Account API

管理基本帳號資訊

取得使用者帳號資訊

更新基本帳號資訊

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

取得驗證紀錄 ID

驗證使用者密碼

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

夾帶驗證紀錄 ID 發送請求

更新使用者密碼

更新或綁定新電子郵件

移除使用者電子郵件

管理手機

綁定新社交連結

移除社交連結

綁定新 WebAuthn Passkey

管理現有 WebAuthn Passkey

綁定新 TOTP

管理備用碼