跳至主要內容

與 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 標示符（API indicator）格式為 https://{your-tenant-id}.logto.app/api，這將是你在存取權杖 (Access token) 請求主體中使用的 resource 值。

Logto Management API details

在存取 Logto Management API 前，請確保你的 M2M 應用程式已被指派包含此內建「Logto Management API」資源 all 權限的 M2M 角色 (Role)。

資訊:

Logto 也為新建立的租戶預先配置了一個「Logto Management API access」M2M 角色，該角色已經指派了 Logto Management API 資源的 all 權限。你可以直接使用，無需手動設定權限。這個預設角色也可以根據需要編輯或刪除。

現在，將上述內容整合並發送請求：

資訊:

自 v1.30.1 版本起，Logto 提供官方 @logto/api Node.js SDK，協助你輕鬆與 Logto Management API 互動。

Logto Cloud​

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// 或者你甚至可以跳過取得存取權杖 (Access token)，直接呼叫 API
const response = await apiClient.GET('/api/users');
console.log(response.data);

自行託管 / OSS​

OSS 使用者應使用 default 作為 tenant ID，並同時提供 baseUrl 與 apiIndicator 設定。

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

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

使用 @logto/api SDK，你可以直接透過下方程式碼片段與任何 Management API 互動。存取權杖 (Access token) 會在內部快取，必要時自動重新整理。

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

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 存取權杖