與 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，你可以存取 Logto 強大且高度可擴展的後端服務，並可應用於多種情境。它的能力遠超過僅靠管理主控台低程式碼功能所能達成的範圍。

常用的 API 如下：

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

如何存取 Logto Management API

建立 M2M 應用程式

備註:

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

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

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

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

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

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

取得存取權杖 (Access token)

存取權杖請求基礎

M2M 應用程式會向權杖端點發送 POST 請求，並在 HTTP 請求實體主體中以 application/x-www-form-urlencoded 格式加入以下參數，以取得存取權杖 (Access token)：

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

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

這是透過在請求的 Authorization 標頭中，以 Basic 驗證 (Basic authentication) 形式包含應用程式憑證來實現的：將 {App ID}:{App Secret} 進行 base64 編碼，並將其設為 Basic 前綴後的值。

你可以在 M2M 應用程式的詳細頁面找到 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 前，請確保你的 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 互動。

Node.js with `@logto/api` SDK
Node.js
cURL

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',
});

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)。

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

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

請記得將實際值替換為你自己的資訊。

警告:

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

Node.js with `@logto/api` SDK
Node.js
cURL

使用 @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);

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

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

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}`,
    },
  });
};

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

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

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

請記得將實際值替換為你自己的。Bearer 後面的值應為你取得的存取權杖 (Access token, JWT)。

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 標頭

分頁回應標頭範例如下：

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。

請求速率限制 (Rate limit)

備註:

僅適用於 Logto Cloud。

Logto Cloud 會針對租戶層級執行執行階段速率限制，以保護系統穩定性。詳情請參閱系統限制 rate-limit 章節。

使用 Logto Management API：逐步指南

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

什麼是 Logto Management API？​

如何存取 Logto Management API​

建立 M2M 應用程式​

取得存取權杖 (Access token)​

存取權杖請求基礎​

取得 Logto Management API 的存取權杖​

Logto Cloud​

自行託管 / OSS​

存取權杖 (Access token) 回應​

存取權杖 (Access token) 回應​

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

Logto Management API 的典型應用情境​

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

進階使用者搜尋​

自行實作組織管理​

使用 Logto Management API 的小技巧​

管理分頁 API 回應​

使用 link 標頭​

使用 total-number 標頭​

更改頁碼與每頁數量​

請求速率限制 (Rate limit)​

相關資源​

什麼是 Logto Management API？

如何存取 Logto Management API

建立 M2M 應用程式

取得存取權杖 (Access token)

存取權杖請求基礎

取得 Logto Management API 的存取權杖

Logto Cloud

自行託管 / OSS

存取權杖 (Access token) 回應

存取權杖 (Access token) 回應

使用存取權杖存取 Logto Management API

Logto Management API 的典型應用情境

自行實作使用者個人檔案

進階使用者搜尋

自行實作組織管理

使用 Logto Management API 的小技巧

管理分頁 API 回應

使用 link 標頭

使用 total-number 標頭

更改頁碼與每頁數量

請求速率限制 (Rate limit)

相關資源