How to Use the Logto Management API: Complete Guide with TypeScript SDK

The Logto Management API is a protected machine-to-machine (M2M) HTTP API that requires OAuth 2.0 client credentials, accessible via the @logto/api SDK which handles authentication, token caching, and type-safe requests.

The Logto Management API allows you to programmatically manage users, applications, roles, organizations, and other resources within the logto-io/logto ecosystem. This guide walks through the implementation details found in the source code, demonstrating how to authenticate and execute type-safe API calls using the official SDK.

Prerequisites and Authentication Setup

Before making requests, you must configure a Machine-to-Machine (M2M) application and grant it appropriate scopes.

Create a Machine-to-Machine Application

Logto uses the OAuth 2.0 client-credentials flow to secure the Management API. You need to create a regular Logto application with the type set to M2M in the Logto Console. This generates a clientId and clientSecret pair that identifies your automated service.

Grant Management API Permissions

In the Console, grant your M2M application the all scope for the Management API. This scope provides full administrative access to manage tenant resources. According to the source code in packages/api/src/management.ts, the SDK uses the allScope constant to reference this permission level.

Installing the Logto API SDK

Install the official SDK package that powers the Management API client:

npm install @logto/api

The SDK leverages openapi-fetch to generate a fully typed client, providing compile-time guarantees for request payloads and response shapes across all Management API endpoints.

Implementing the Client Credentials Flow

The authentication logic lives in packages/api/src/client-credentials.ts, which implements a robust token management system.

Token Acquisition and Caching

The ClientCredentials class handles the OAuth 2.0 flow by posting a grant_type=client_credentials request to https://{tenant}.logto.app/oidc/token. The response contains the access token, expiry timestamp, and granted scope.

The class automatically caches the token and refreshes it when approaching expiration. By default, the SDK uses a 60-second leeway, fetching a new token before the current one expires to prevent request failures.

Making Type-Safe Management API Calls

The createManagementApi factory function in packages/api/src/management.ts wires together the authentication layer and the HTTP client. It performs three critical operations:

1. Builds the base URL via getBaseUrl (https://{tenant}.logto.app)
2. Sets the API indicator via getManagementApiIndicator (…/api)
3. Creates an apiClient via createApiClient that automatically injects Authorization: Bearer … headers

Logto Cloud (Tenant-Hosted)

For Logto Cloud users, pass your tenant ID to the factory:

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

const { apiClient, clientCredentials } = createManagementApi('my-tenant-id', {
  clientId: 'YOUR_M2M_CLIENT_ID',
  clientSecret: 'YOUR_M2M_CLIENT_SECRET',
});

// Example: list all users
const usersResponse = await apiClient.GET('/api/users');
console.log('Users:', usersResponse.data);

Self-Hosted Instances

For self-hosted or OSS deployments, explicitly provide the baseUrl and apiIndicator:

const { apiClient: ossClient } = createManagementApi('default', {
  clientId: 'YOUR_M2M_CLIENT_ID',
  clientSecret: 'YOUR_M2M_CLIENT_SECRET',
  baseUrl: 'https://my-logto.example.com',
  apiIndicator: 'https://my-logto.example.com/api',
});

// Example: create a new application
const newApp = await ossClient.POST('/api/applications', {
  json: {
    name: 'My Awesome App',
    type: 'SPA',
  },
});
console.log('Created app:', newApp.data);

Advanced: Custom Token Retrieval

If you need full control over token retrieval—such as using Redis for distributed caching or integrating with a third-party identity provider—bypass the helper and build the client directly:

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

const client = createApiClient({
  baseUrl: 'https://my-logto.example.com',
  getToken: async () => {
    // Your own logic – maybe a Redis cache or external IdP
    const token = await fetchMyToken();
    return token;
  },
});

// Type-safe call to update an application
await client.PATCH('/api/applications/{id}', {
  params: { path: { id: 'app-id' } },
  json: { name: 'Renamed App' },
});

Key Source Files and Architecture

Understanding the underlying implementation helps when debugging or extending functionality:

• packages/api/src/management.ts – Contains the public factory (createManagementApi, createApiClient) and utility helpers (getBaseUrl, getManagementApiIndicator, allScope).
• packages/api/src/client-credentials.ts – Implements the OAuth 2.0 client-credentials flow, token caching, and automatic refresh logic with configurable expiry leeway.
• packages/core/src/middleware/koa-management-api-hooks.ts – Server-side middleware that protects Management API routes in the Logto Core server, validating the resource claim in incoming tokens.

Summary

• Authentication: The Logto Management API requires an M2M application with the all scope, implementing the OAuth 2.0 client-credentials flow.
• SDK Location: The client SDK resides in packages/api/src/management.ts and packages/api/src/client-credentials.ts.
• Token Management: Automatic caching and refresh occur with a default 60-second expiry buffer.
• Type Safety: The SDK uses openapi-fetch to provide compile-time type checking for all endpoints.
• Flexibility: Use createManagementApi for standard implementations or createApiClient with a custom getToken function for advanced use cases.

Frequently Asked Questions

What authentication flow does the Logto Management API use?

The Management API uses the OAuth 2.0 client-credentials flow. The SDK's ClientCredentials class in packages/api/src/client-credentials.ts automates the process of exchanging your M2M client's ID and secret for a bearer token at the https://{tenant}.logto.app/oidc/token endpoint.

How does token caching work in the Logto API SDK?

The ClientCredentials class stores the access token in memory after the initial request. It automatically refreshes the token when it is within 60 seconds of expiration, ensuring subsequent API calls use valid credentials without manual intervention.

Can I use the Logto Management API without the official SDK?

Yes, you can interact with the API using any HTTP client by manually implementing the OAuth 2.0 client-credentials flow. You must obtain a token from the OIDC token endpoint and include it in the Authorization: Bearer header for all requests to https://{tenant}.logto.app/api endpoints.

What resources can I manage through the Logto Management API?

According to the source implementation, you can programmatically manage users, applications (including SPAs and traditional web apps), roles, organizations, connectors, and various tenant settings. The openapi-fetch client provides type definitions for all available endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}