跳至主要內容

與 Management API 互動

什麼是 Logto Management API？​

Logto Management API 是一組完整的 API，讓開發者能完全掌控實作細節，以符合產品需求與技術棧。它已預先建立，並列於 主控台 > API 資源 > Logto Management API，且無法刪除或修改。

其識別碼格式為 https://[tenant-id].logto.app/api

備註:

Logto Management API 的識別碼在 Logto Cloud 與 Logto Open Source 版本間有所不同：

  • Logto Cloud：https://[tenant-id].logto.app/api
  • Logto OSS：https://default.logto.app/api

以下範例皆以 Cloud 版本識別碼為例。

Logto Management API Resource Logto Management API Details

透過 Logto Management API，你可以存取 Logto 強大的後端服務，這些服務具高度擴展性，能應用於多種情境。它的能力遠超過僅靠管理主控台低程式碼功能所能達成的範圍。

常用 API 如下：

想瞭解更多可用 API，請造訪 https://openapi.logto.io/。

如何存取 Logto Management API​

建立 M2M 應用程式​

備註:

如果你尚未熟悉 M2M（機器對機器）驗證流程，建議先閱讀 瞭解驗證流程 以掌握基本概念。

前往 主控台 > 應用程式，選擇「機器對機器」應用程式類型並開始建立流程。

在建立 M2M 應用程式的過程中，你會被導向一個頁面，可以為你的應用程式指派 M2M 角色 (M2M roles)：

指派 M2M 角色視窗 (Assign M2M roles modal)

或者，當你已經建立好 M2M 應用程式後，也可以在 M2M 應用程式詳細頁面指派這些角色：

指派 M2M 角色頁面 (Assign M2M roles page)

在角色指派模組中，你可以看到所有 M2M 角色，帶有 Logto 圖示的角色表示包含 Logto Management API 權限。

現在，請為你的 M2M 應用程式指派包含 Logto Management API 權限的 M2M 角色。

取得存取權杖 (Access token)​

存取權杖請求基本說明​

M2M 應用程式向權杖端點發出 POST 請求，以 application/x-www-form-urlencoded 格式在 HTTP 請求實體中加入以下參數來獲取存取權杖：

  • grant_type：必須設為 client_credentials
  • resource：你想要存取的資源
  • scope：存取請求的權限範圍

你還需要在請求標頭中包含 M2M 應用程式的憑證，以便權杖端點驗證你的 M2M 應用程式。

這是透過在請求的 Authorization 標頭中以 基本驗證 (Basic authentication) 形式包含應用程式的憑證來實現的，其中用戶名是 App ID，密碼是 App Secret。

你可以在 M2M 應用程式的詳細資訊頁面找到 App ID 和 App Secret：

App ID 和 App Secret

取得 Logto Management API 的存取權杖​

Logto 提供了一個內建的「Logto Management API」資源，這是一個具有 all 權限的唯讀資源，用於存取 Logto Management API，你可以在你的 API 資源列表中看到它。資源 API 標示符的格式為 https://{your-tenant-id}.logto.app/api，這將是你在存取權杖請求主體中使用的資源值。

Logto Management API 詳細資訊

在存取 Logto Management API 之前，確保你的 M2M 應用程式已被分配了包含此內建「Logto Management API」資源的 all 權限的 M2M 角色。

資訊:

Logto 也為新創建的租戶提供了一個預先配置的「Logto Management API 存取」M2M 角色，該角色已經被分配了 Logto Management API 資源的所有權限。你可以直接使用它而無需手動設置權限。此預先配置的角色也可以根據需要進行編輯和刪除。

現在，將我們所有的內容組合起來並發送請求：

const logtoEndpoint = 'https://your.logto.endpoint'; // 用你的 Logto endpoint 替換
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};
警告:

對於 Logto Cloud 使用者：當你與 Logto Management API 互動時，不能使用自訂域名，請使用預設的 Logto endpoint https://{your_tenant_id}.logto.app/oidc/token 來授予存取權杖。

存取權杖回應​

成功取得存取權杖的回應內容如下：

{
  "access_token": "eyJhbG...2g", // 使用此權杖存取 Logto Management API
  "expires_in": 3600, // 權杖有效時間（秒）
  "token_type": "Bearer", // 使用存取權杖時的授權類型
  "scope": "all" // Logto Management API 的權限範圍 (scope) 為 all
}
備註:

Logto 目前不支援將 M2M 應用程式表示為使用者。存取權杖 (Access token) 負載中的 sub 將是應用程式 ID。

使用存取權杖存取 Logto Management API​

你可能會注意到權杖回應中有一個 token_type 欄位，其固定為 Bearer。

因此，當你與 API 資源 (API resource) 伺服器互動時，應將存取權杖 (Access token) 以 Bearer 格式（Bearer YOUR_TOKEN）放在 HTTP 標頭的 Authorization 欄位中。

使用請求的存取權杖 (Access token) 與內建的 Logto Management API 資源 https://[your-tenant-id].logto.app/api 來獲取 Logto 中的所有應用程式：

const logtoEndpoint = 'https://your.logto.endpoint'; // 用你的 Logto endpoint 替換
const accessToken = 'eyJhb...2g'; // 存取權杖 (Access Token)

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

Logto Management API 的典型應用場景​

我們的開發者已利用 Logto Management API 實作許多進階功能。我們相信這套 API 具高度擴展性，能滿足你各種需求。以下舉幾個僅能透過 Logto Management API 實現、無法在 Logto 管理主控台完成的應用場景：

自行實作使用者個人檔案​

Logto 目前尚未提供預設的使用者個人檔案 UI 解決方案。我們理解個人檔案與業務、產品屬性密切相關。在我們持續探索最佳方案的同時，建議你利用 API 自行開發。例如，你可以結合互動 API、個人檔案 API、驗證碼 API，打造符合需求的自訂解決方案。

Logto 管理主控台支援基本搜尋與篩選功能。若需模糊搜尋、精確比對、區分大小寫等進階搜尋選項，請參考我們的 進階使用者搜尋 教學與指南。

自行實作組織管理​

如果你利用 組織 (Organizations) 功能打造多租戶應用，可能會需要 Logto Management API 來處理組織邀請、成員管理等任務。對於你的 SaaS 產品，當租戶中同時有管理員與成員時，Logto Management API 能協助你打造專屬的管理後台。詳情請參閱 這裡。

使用 Logto Management API 的小技巧​

處理分頁 API 回應​

部分 API 回應可能包含大量結果，這些結果會以分頁方式呈現。Logto 提供兩種分頁資訊。

分頁回應的標頭範例如下：

Link: <https://logto.dev/users?page=1&page_size=20>; rel="first"

link 標頭會提供上一頁、下一頁、第一頁、最後一頁的 URL：

  • 上一頁的 URL 對應 rel="prev"
  • 下一頁的 URL 對應 rel="next"
  • 最後一頁的 URL 對應 rel="last"
  • 第一頁的 URL 對應 rel="first"

使用 total-number 標頭​

除了標準的 link 標頭外，Logto 也會加上 Total-Number 標頭：

Total-Number: 216

這對於顯示頁碼非常方便實用。

更改頁碼與每頁數量​

有兩個可選查詢參數：

  • page：指定頁碼，從 1 開始，預設值為 1。
  • page_size：指定每頁項目數，預設值為 20。

請求速率限制​

備註:

僅適用於 Logto Cloud。

為確保所有使用者的服務穩定與安全，我們採用通用防火牆監控並管理網站流量。雖然未強制設置嚴格速率限制，但建議每 10 秒內請求數量不超過約 200 次，以避免觸發保護機制。

使用 Logto Management API：逐步指南

使用 Postman 幾分鐘內取得 M2M 存取權杖