與 Management API 互動

什麼是 Logto Management API？

Logto Management API 是一套完整的 API，讓開發者能夠完全控制其實作，以符合產品需求和技術堆疊。它是預先建置的，列在 Console > API 資源 > Logto Management API 中，且無法刪除或修改。

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

透過 Logto Management API，你可以存取 Logto 強大的後端服務，這些服務具有高度擴展性，並可用於多種情境。它超越了管理控制台的低代碼能力。

以下是一些常用的 API：

欲了解更多可用的 API，請造訪 https://openapi.logto.io/。

如何存取 Logto Management API

建立 M2M 應用程式

備註:

如果你不熟悉 M2M（機器對機器）驗證流程，我們建議先閱讀理解驗證流程以了解基本概念。

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

在創建 M2M 應用程式的過程中，你將被引導至一個頁面，在此頁面上可以為你的應用程式指派 M2M 角色 (Roles)：

或者，你也可以在已創建的 M2M 應用程式詳細頁面上指派這些角色：

在角色分配模組中，你可以看到所有 M2M 角色都已包含，帶有 Logto 圖示的角色表示這些角色包含 Logto Management API 權限。

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

取得存取權杖

存取權杖請求的基本知識

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：

取得 Logto Management API 的存取權杖

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

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

資訊:

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

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

Node.js
cURL

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

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'

記得用你自己的實際值替換。

警告:

對於 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 的權限範圍 `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 中的所有應用程式：

Node.js
cURL

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

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

記得將實際值替換為你自己的。在 Bearer 之後的值應為你收到的存取權杖 (JWT)。

使用 Logto Management API 的典型情境

我們的開發者已使用 Logto Management API 實現了許多額外功能。我們相信我們的 API 具有高度擴展性，能夠支持廣泛的需求。以下是一些無法透過 Logto 管理控制台實現，但可以透過 Logto Management API 達成的情境範例。

自行實作使用者檔案

Logto 目前不提供預建的使用者檔案 UI 解決方案。我們認識到使用者檔案與業務和產品屬性密切相關。在我們努力找出最佳方法的同時，建議使用我們的 API 來創建自己的解決方案。例如，你可以利用我們的互動 API、檔案 API 和驗證碼 API 來開發符合需求的自訂解決方案。

進階使用者搜尋

Logto 管理控制台支持基本的搜尋和篩選功能。若需進階搜尋選項，如模糊搜尋、精確匹配和區分大小寫，請參閱我們的進階使用者搜尋教程和指南。

自行實作組織管理

如果你正在使用組織功能來構建多租戶應用程式，可能需要 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"

連結標頭提供了前一頁、下一頁、第一頁和最後一頁結果的 URL：

前一頁的 URL 後跟 rel="prev"。
下一頁的 URL 後跟 rel="next"。
最後一頁的 URL 後跟 rel="last"。
第一頁的 URL 後跟 rel="first"。

使用總數標頭

除了標準的連結標頭外，Logto 還會添加一個 Total-Number 標頭：

Total-Number: 216

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

更改頁碼和頁面大小

有兩個可選的查詢參數：

page：表示頁碼，從 1 開始，預設值為 1。
page_size：表示每頁的項目數，預設值為 20。

速率限制

備註:

這僅適用於 Logto Cloud。

為確保我們的服務對所有使用者的可靠性和安全性，我們使用一般防火牆來監控和管理網站流量。雖然我們不強制執行嚴格的速率限制，但建議使用者將活動限制在每 10 秒約 200 次請求，以避免觸發我們的保護措施。

使用 Logto Management API：逐步指南

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

什麼是 Logto Management API？​

如何存取 Logto Management API​

建立 M2M 應用程式​

取得存取權杖​

存取權杖請求的基本知識​

取得 Logto Management API 的存取權杖​

存取權杖回應​

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

使用 Logto Management API 的典型情境​

自行實作使用者檔案​

進階使用者搜尋​

自行實作組織管理​

使用 Logto Management API 的提示​

管理分頁的 API 回應​

使用連結標頭​

使用總數標頭​

更改頁碼和頁面大小​

速率限制​

相關資源​