跳至主要內容

透過 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 標頭即可。
備註:

為確保存取權杖 (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>'

管理基本帳號資訊​

取得使用者帳號資訊​

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

回應內容範例如下：

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

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

更新基本帳號資訊​

基本帳號資訊包含使用者名稱、姓名、頭像與個人資料。

若要更新使用者名稱、姓名與頭像，可使用 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":"..."}'

若要更新個人資料，可使用 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。此 ID 可用於在更新識別資訊時驗證使用者身分。

取得驗證紀錄 ID 的方式：驗證使用者密碼，或向使用者的電子郵件 / 手機發送驗證碼。

更多驗證相關內容，請參閱 透過 Account API 進行安全驗證。

驗證使用者密碼​

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

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

備註:

使用此方法前，需先 設定電子郵件連接器 或 SMS 連接器，並確保已配置 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 更新使用者識別資訊。

夾帶驗證紀錄 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":"..."}'

驗證成功後，即可更新使用者電子郵件，於請求內容中將 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>'

管理手機​

備註:

使用此方法前，需先 設定 SMS 連接器，並確保已配置 BindNewIdentifier 範本。

與更新電子郵件類似，可使用 PATCH /api/my-account/primary-phone 端點更新或綁定新手機，並用 DELETE /api/my-account/primary-phone 端點移除使用者手機。

要綁定新社交連結，需先請求授權網址：

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>'
備註:

請先 啟用 MFA 與 WebAuthn。

備註:

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

步驟 0：將你的前端應用程式來源加入相關來源清單。

瀏覽器中的 passkey 綁定於特定主機名稱（RP ID），僅該 RP ID 的來源可註冊或驗證 passkey。但你的前端應用程式與 Logto 登入頁面來源不同，因此需將前端應用程式來源加入相關來源清單，才能在其他 RP ID 下註冊 / 驗證 passkey。

預設情況下，Logto 會將 RP ID 設為租戶網域，例如 https://example.logto.app 則 RP ID 為 example.logto.app。若使用自訂網域，RP ID 則為自訂網域，如 https://auth.example.com 則 RP ID 為 auth.example.com。

現在，假設你的前端應用程式來源為 https://account.example.com，請將其加入相關來源：

curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

更多相關來源說明，請參閱 Related Origin Requests 文件。

步驟 1：請求新的註冊選項。

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

步驟 2：於本地瀏覽器註冊 passkey。

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

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

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

步驟 3：驗證 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。

步驟 4：最後，綁定 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 的 user agent。

更新 passkey 名稱：

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：

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>'
備註:

請先 啟用 MFA 與 TOTP。

備註:

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

步驟 1：產生 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 後，需驗證並綁定至帳號：

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：產生新備用碼：

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：將備用碼顯示給使用者：

important:

在將備用碼綁定至使用者帳號前，必須顯示給使用者並提醒：

  • 立即下載或抄寫這些備用碼
  • 妥善保存於安全處
  • 每組備用碼僅能使用一次
  • 若失去主要 MFA 方法，這些備用碼是最後救援手段

請以清楚、易於複製的格式顯示備用碼，並考慮提供下載選項（如文字檔或 PDF）。

步驟 3：將備用碼綁定至使用者帳號：

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）。
  • 每組備用碼僅能使用一次。

查看現有備用碼：

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。