使用 Account API 設定帳戶

什麼是 Logto Account API

Logto Account API 是一組完整的 API，讓終端使用者可以直接存取 API，而不需要透過 Management API。以下是其亮點：

直接存取：Account API 讓終端使用者可以直接存取並管理自己的帳戶資料，而不需要透過 Management API。
使用者資料和身分管理：使用者可以完全管理自己的資料和安全設定，包括更新電子郵件、電話和密碼等身分資訊，以及管理社交連結。MFA 和 SSO 支援即將推出。
全域存取控制：管理員擁有完整的全域控制權，可以自訂每個欄位。
無縫授權：授權變得前所未有的簡單！只需使用 client.getAccessToken() 取得 Logto 的不透明存取權杖，並將其附加到 Authorization 標頭中作為 Bearer <access_token>。

使用 Logto Account API，你可以建立一個自訂的帳戶管理系統，例如與 Logto 完全整合的個人資料頁面。

以下列出一些常見的使用案例：

取得使用者資料
更新使用者資料
更新使用者密碼
更新使用者身分，包括電子郵件、電話和社交連結
管理 MFA 因素（驗證）
管理使用者會話
管理使用者授權的應用程式（授權）

要瞭解更多可用的 API，請造訪 Logto Account API 參考和 Logto Verification API 參考。

備註:

SSO 帳戶檢視和帳戶刪除功能目前可透過 Logto Management API 使用。請參閱使用 Management API 設定帳戶以獲取實作細節。

如何啟用 Account API

前往控制台 > 登入與帳戶 > 帳戶中心。

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

啟用後，為識別符、資料和第三方權杖存取配置每個欄位的權限。每個欄位支援 Off、ReadOnly 或 Edit；預設為 Off。

安全欄位：
- 欄位包括：主要電子郵件、主要電話、社交身分、密碼和 MFA。
- 在終端使用者編輯這些欄位之前，他們必須透過密碼、電子郵件或簡訊驗證其身分，以獲得 10 分鐘的驗證記錄 ID。請參閱取得驗證記錄 ID。
- 若要使用 WebAuthn 密鑰作為 MFA，請將你的前端應用程式網域新增到 WebAuthn 相關來源，以便帳戶中心和登入體驗可以共享密鑰。請參閱連結新的 WebAuthn 密鑰。
資料欄位：
- 欄位包括：使用者名稱、姓名、大頭貼、資料（其他標準資料屬性）和自訂資料。
- 終端使用者可以在不需額外驗證的情況下編輯這些欄位。
秘密保管庫：
- 對於 OIDC 或 OAuth 社交和企業連接器，Logto 秘密保管庫在驗證後安全地儲存第三方存取和重新整理權杖。應用程式可以呼叫外部 API，例如同步 Google 日曆事件，而不需再次提示使用者登入。權杖檢索在啟用 Account API 後自動可用。
會話管理：
- 啟用後，使用者可以檢視和管理其活動會話，包括裝置資訊和上次登入時間。使用者還可以撤銷會話以從特定裝置登出。
- 此 Sessions 欄位權限也控制使用者授權的應用程式（授權）API（檢視和撤銷授權）。
- 在終端使用者存取會話管理之前，他們必須透過密碼、電子郵件或簡訊驗證其身分，以獲得 10 分鐘的驗證記錄 ID。請參閱取得驗證記錄 ID。

如何存取 Account API

備註:

為確保存取權杖具有適當的權限，請確保你已在 Logto 配置中正確配置相應的權限範圍。

例如，對於 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, // 用於管理使用者資料
    UserScope.Sessions, // 用於管理使用者會話和應用程式授權
  ],
};

取得存取權杖

在應用程式中設置 SDK 後，你可以使用 client.getAccessToken() 方法來取得存取權杖。此權杖是不透明權杖，可用於存取 Account API。

如果你未使用官方 SDK，應在存取權杖授權請求 /oidc/token 中將 resource 設為空。

使用存取權杖存取 Account API

在與 Account API 互動時，應在 HTTP 標頭的 Authorization 欄位中包含存取權杖，格式為 Bearer (Bearer YOUR_TOKEN)。

以下是一個取得使用者帳戶資訊的範例：

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 (資料頁面 URL), 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

首先，你需要取得一個具有 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 發送請求

在發送請求以更新使用者的識別符時，你需要在請求標頭中包含驗證記錄 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 設定的密碼必須符合你在控制台 > 安全 > 密碼政策中配置的密碼政策。如果密碼不符合政策，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 連結的任何電子郵件必須通過你在控制台 > 安全 > 封鎖清單中配置的封鎖清單驗證。如果電子郵件違反政策，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 端點來移除使用者的電話。

要連結新的社交連結，首先你應請求授權 URL，使用 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：使用者授權應用程式後的重定向 URI，你應在此 URL 上託管一個網頁並捕獲回調。
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 端點來連結社交連結。

兩個不同的驗證記錄 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 驗證頁面不同的網域呼叫 Account API，你需要配置 相關來源 以允許跨來源密鑰操作。

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 個不同的網域作為相關來源，請參閱相關來源請求文件以獲取詳細資訊。

步驟 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 中伺服器返回的資料
});
// 保存回應以供後續使用

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

使用 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 碼或直接顯示給使用者。使用者應將其新增到其驗證器應用程式（例如 Google Authenticator、Microsoft Authenticator 或 Authy）。

QR 碼的 URI 格式應為：

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

範例：

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

步驟 3：綁定 TOTP 因素

使用者將秘密新增到其驗證器應用程式後，他們需要驗證並將其綁定到其帳戶。使用 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。

管理使用者會話

列出活動會話

要列出使用者的活動會話，你可以使用 GET /api/my-account/sessions 端點。

備註:

需要 UserScope.Sessions 權限範圍才能存取此端點。
帳戶中心設定中的 Sessions 欄位必須設為 ReadOnly 或 Edit。

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

按會話 ID 撤銷會話

要撤銷特定會話，使用 DELETE /api/my-account/sessions/{sessionId} 端點。

備註:

需要 UserScope.Sessions 權限範圍才能存取此端點。
帳戶中心設定中的 Sessions 欄位必須設為 Edit。

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

可選查詢參數：

revokeGrantsTarget：可選地指定要撤銷的授權目標。可能的值：
- all：撤銷與會話相關的所有授權。
- firstParty：僅撤銷與會話相關的第一方應用程式授權。（推薦用於大多數使用案例，因為它撤銷你自己的應用程式的存取權，同時保留第三方應用程式授權，提供更好的使用者體驗。）
- 未指定：預設行為撤銷不具有 offline_access 權限範圍的授權，這通常意味著撤銷會話的非重新整理權杖授權。

管理使用者授權的應用程式（授權）

當使用者需要從其帳戶設定頁面檢視和撤銷授權的應用程式時，使用使用者授權的應用程式（授權）API。

備註:

應用程式授權 API 與會話 API 共享相同的權限模型。
需要 UserScope.Sessions 權限範圍。
帳戶中心設定中的 Sessions 欄位必須啟用：
- ReadOnly 或 Edit 以列出授權。
- Edit 以撤銷授權。

列出活動應用程式授權

要列出當前使用者的活動應用程式授權，使用 GET /api/my-account/grants 端點。

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

可選查詢參數：

appType=firstParty：僅返回第一方應用程式授權。
appType=thirdParty：僅返回第三方應用程式授權。
省略 appType：返回所有活動授權。

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

按授權 ID 撤銷應用程式授權

要撤銷特定應用程式授權，使用 DELETE /api/my-account/grants/{grantId} 端點。

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

當授權被撤銷時，先前發出的不透明存取權杖和重新整理權杖將失效。

什麼是 Logto Account API​

如何啟用 Account API​

如何存取 Account API​

取得存取權杖​

使用存取權杖存取 Account API​

管理基本帳戶資訊​

取得使用者帳戶資訊​

更新基本帳戶資訊​

管理識別符和其他敏感資訊​

取得驗證記錄 ID​

驗證使用者的密碼​

向使用者的電子郵件或電話發送驗證碼​

使用驗證記錄 ID 發送請求​

更新使用者的密碼​

更新或連結新的電子郵件​

移除使用者的電子郵件​

管理電話​

連結新的社交連結​

移除社交連結​

連結新的 WebAuthn 密鑰​

管理現有的 WebAuthn 密鑰​

連結新的 TOTP​

管理備份碼​

管理使用者會話​

管理使用者授權的應用程式（授權）​

什麼是 Logto Account API

如何啟用 Account API

如何存取 Account API

取得存取權杖

使用存取權杖存取 Account API

管理基本帳戶資訊

取得使用者帳戶資訊

更新基本帳戶資訊

管理識別符和其他敏感資訊

取得驗證記錄 ID

驗證使用者的密碼

向使用者的電子郵件或電話發送驗證碼

使用驗證記錄 ID 發送請求

更新使用者的密碼

更新或連結新的電子郵件

移除使用者的電子郵件

管理電話

連結新的社交連結

移除社交連結

連結新的 WebAuthn 密鑰

管理現有的 WebAuthn 密鑰

連結新的 TOTP

管理備份碼

管理使用者會話

管理使用者授權的應用程式（授權）