跳至主要內容

透過 Account API 管理帳戶設定

什麼是 Logto Account API​

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

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

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

常見用途如下：

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

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

備註:

以下設定的專屬 Account API 即將推出：MFA、多重要素驗證 (MFA)、單一登入 (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：社交連結。

更多 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 的方式：可驗證使用者密碼，或向使用者的電子郵件 / 手機發送驗證碼。

驗證使用者密碼​

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 發送請求​

在發送更新使用者身分識別的請求時，需將驗證記錄 ID 以 logto-verification-id 欄位附加於請求標頭。

備註:

使用此方法前，需先 設定電子郵件連接器，並確保已設定 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 PATCH 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>'