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

> Master the Logto Management API with our comprehensive TypeScript SDK guide. Securely manage your users and applications through type-safe requests and SDK-handled authentication. Get started today.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-05

---

**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`](https://github.com/logto-io/logto/blob/main/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:

```bash
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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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:

```typescript
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`:

```typescript
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:

```typescript
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`](https://github.com/logto-io/logto/blob/main/packages/api/src/management.ts)** – Contains the public factory (`createManagementApi`, `createApiClient`) and utility helpers (`getBaseUrl`, `getManagementApiIndicator`, `allScope`).
- **[`packages/api/src/client-credentials.ts`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/packages/api/src/management.ts) and [`packages/api/src/client-credentials.ts`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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.