跳至主要內容

使用 Account API 設定帳戶

什麼是 Logto Account API​

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

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

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

以下列出一些常見的使用方式：

  • 取得使用者資料
  • 更新使用者資料
  • 更新使用者密碼
  • 更新使用者身分，包括電子郵件、電話和社交連結

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

備註:

以下設定的專用 Account API 即將推出：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​

獲取存取權杖​

在應用程式中設置 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>'

管理基本帳戶資訊​

獲取使用者帳戶資訊​

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 需要對涉及識別符和其他敏感資訊的操作進行額外的授權。

獲取驗證記錄 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 PATCH 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 PATCH 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 端點移除使用者的電話。

要連結新的社交連結，首先你應請求授權 URL：

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 端點連結社交連結。

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>'