Skip to main content

Set up your app service with the Logto Management API

Use the Logto Management API to build custom organization flows in your app. Below are the basic setup steps for integrating the Management API. If you’re already familiar, you can skip ahead to the tutorial.

Once you’re familiar with the setup, you can explore additional APIs to tailor the rest of the flows to your business needs.

Establish a machine-to-machine connection​

Logto uses machine‑to‑machine (M2M) authentication to securely connect your backend service to the Logto Management API endpoint. Your backend service can then use the Management API to handle organization-related tasks such as creating organizations, adding or removing members, and more.

This involves:

  1. Create a Machine-to-Machine (M2M) app in the Logto Console.
M2M app details
  1. Acquire an M2M access token from Logto. Learn more.
  2. Call Logto Management APIs from your backend service. For example, list all organizations:
curl \
 -X GET https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json"

Protect your app server​

Because end users can perform certain organization operations self‑serve, add an authorization layer between the end user and your app server. The server should mediate every request, validate the user’s organization‑scoped token and required scopes, and only then use a server‑held M2M credential to invoke the Management API.

When a user presents an organization token to request an action (for example, creating an organization), the server first validates the scopes in the token. If the token includes the necessary scope, such as org:create, authorize the request and call the Logto Management API via the M2M flow to create the organization.

If the token doesn’t contain the required scopes, return a 403 Forbidden and skip the M2M logic. This ensures users without the appropriate privileges cannot create organizations.

Below are common authorization patterns.

Using organization permissions​

First, make sure you have defined organization permissions and roles in your organization template in the previous section.

Then, ensure that UserScope.Organizations (value: urn:logto:organization) is included in the Logto config. Take the React SDK as an example:

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

const config = {
  endpoint: 'https://<tenant-id>.logto.app/', // Your Logto endpoint
  appId: '40fmibayagoo00lj26coc', // Your app id
  resources: [
    'https://my.company.com/api', // Your global API resource identifier
  ],
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations, // Request an organization token
  ],
};

This ensures that when calling getOrganizationToken(organizationId), the client SDK requests an organization token that contains the organization permissions assigned to the user. Your backend service can then validate the token and authorize subsequent requests based on these permissions.

For details on protecting organization‑level (non‑API) permissions, see the full guide.

Mixing organization-level permissions and API-level permissions​

This applies when your API resources and permissions are registered globally, but roles are defined at the organization level (you can assign API‑level permissions to organization roles in the organization template).

The implementation is the same as the previous section. Always provide the organization ID and call getOrganizationToken(organizationId) to fetch an organization token; otherwise, organization permissions won’t be included.

For details on protecting organization‑level API permissions, see the full guide.