跳至主要內容

透過 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 ReferenceLogto 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 欄位用於自訂欄位,值可為 OffEditReadOnly,預設為 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": "..."
}

透過發送驗證碼至電子郵件或手機驗證

備註:

使用此方式前,需先設定電子郵件連接器設定簡訊連接器,並確保已配置 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。

備註:

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

管理手機

備註:

使用此方式前,需先設定簡訊連接器,並確保已配置 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:將前端應用程式的 origin 加入相關 origins。

瀏覽器中的 Passkey 綁定於特定 hostname(RP ID),僅 RP ID 的 origin 可註冊或驗證 Passkey。但你的前端應用程式與 Logto 登入頁的 origin 不同,因此需將前端應用程式的 origin 加入相關 origins 清單,才能在其他 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

現在,將你的前端應用程式 origin(如 https://account.example.com)加入相關 origins:

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"]}'

更多相關 origins 說明,請參閱 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 本地瀏覽器回傳的 response。
  • 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 的使用者代理資訊。

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