跳至主要內容

使用 Logto Management API 設定你的應用服務

Logto 提供強大的 Management API，讓你能在應用程式內建立並自訂專屬的組織 (Organization) 流程。 理解其運作方式是設計自訂流程的關鍵。以下為整合 Management API 以實現組織使用體驗的基本步驟與概要。

如果你已熟悉基礎內容，可直接前往 教學。熟悉設定後，還能探索更多 API，根據業務需求調整其餘流程。

建立機器對機器連線​

Logto 使用 機器對機器 (M2M, Machine-to-Machine) 驗證 (Authentication)，安全地將你的後端服務連接至 Logto Management API 端點。 你的後端服務即可透過 Management API 處理組織相關任務，例如建立組織、新增或移除成員等。

步驟如下：

  1. 在 Logto Console 建立一個機器對機器 (M2M) 應用程式。
M2M app details
  1. 從 Logto 取得 M2M 存取權杖 (Access token)。進一步了解。
  2. 從你的後端服務 呼叫 Logto Management API。例如，列出所有組織：
curl \
 -X GET https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json"

保護你的應用伺服器​

由於終端使用者可自行執行部分組織操作，因此在終端使用者與應用伺服器之間加入授權 (Authorization) 層至關重要。你可以根據所使用的 Logto Management API 端點及產品 API 架構，選擇全域或組織層級套用此授權層。伺服器應攔截每個請求，驗證使用者的組織權杖 (Organization token) 及所需權限範圍 (Scopes)，僅在通過驗證後，才以伺服器持有的 M2M 憑證呼叫 Management API。

當使用者提交組織權杖請求操作（例如建立組織）時，伺服器會先驗證權杖中的權限範圍 (Scopes)。若權杖包含必要權限範圍（如 org:create），則授權請求並透過 M2M 流程呼叫 Logto Management API 建立組織。

若權杖未包含所需權限範圍，則回傳 403 Forbidden 並略過 M2M 邏輯。如此可確保未具備適當權限的使用者無法建立組織。

以下為常見授權 (Authorization) 模式。

使用組織權限 (Organization permissions)​

首先，請確保你已在前一節的組織範本中定義組織權限與角色。

接著，確認 Logto 設定中已包含 UserScope.Organizations（值：urn:logto:organization）。以 React SDK 為例：

// src/App.js
import { UserScope } from '@logto/react';

const config = {
  endpoint: 'https://<tenant-id>.logto.app/', // 你的 Logto 端點
  appId: '40fmibayagoo00lj26coc', // 你的 app id
  resources: [
    'https://my.company.com/api', // 你的全域 API 資源識別符
  ],
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations, // 請求組織權杖 (Organization token)
  ],
};

這可確保當呼叫 getOrganizationToken(organizationId) 時，client SDK 會請求包含分配給使用者之組織權限的組織權杖。你的後端服務即可驗證該權杖，並根據這些權限授權後續請求。

關於保護組織層級（非 API）權限，詳見完整指南。

使用 API 層級權限 (API-level permissions)​

當你的 API 資源與權限為全域註冊，但角色於組織層級定義時（你可在組織範本中將 API 層級權限指派給組織角色），適用此模式。

實作方式與前述相同。務必提供組織 ID 並呼叫 getOrganizationToken(organizationId) 以取得組織權杖，否則不會包含組織權限。

關於保護組織層級 API 權限，詳見完整指南。

使用全域 RBAC (Global RBAC)​

此情境下，你可利用 Logto Management API 實作系統層級存取控制。

在多租戶環境中，常見模式是設有超級使用者或超級管理員角色。例如，若你以 Logto 建立 SaaS 平台，可能希望有一位超級使用者能直接在自家應用內管理所有客戶組織，無需登入 Logto Console。

此超級使用者可執行更高層級操作，如批次建立或刪除組織，這些操作需超越單一組織範疇的系統權限。為實現此目標，請在 Logto 註冊 API 資源，並結合 Logto Management API，利用全域 RBAC 管理這些權限。

關於 RBAC 整合與存取控制管理，詳見完整指南。