Logto API for Managing Users: Complete Management API Reference

The Logto Management API is a machine-to-machine (M2M) REST API secured with OAuth 2.0 client credentials that provides comprehensive endpoints for user CRUD operations, role assignments, and session management under the /api/ base path.

The logto-io/logto repository exposes a powerful Management API that enables programmatic control over the entire user lifecycle. This Logto API for managing users allows administrators to create, update, delete, and query user accounts, manage roles, and handle sessions through a type-safe, OpenAPI-compliant interface.

Authentication and Access Model

The Management API follows the OAuth 2.0 client credentials flow. You must create an M2M application in the Logto Console and grant it Management API permissions. The SDK automatically handles token fetching and injects the Authorization: Bearer <token> header for every request except .well-known routes.

Core User Management Endpoints

All endpoints operate under the base path /api/ and return JSON responses.

List and Retrieve Users

• GET /api/users - Retrieves paginated user lists with optional filtering, search, and ordering parameters.
• GET /api/users/:userId - Fetches a single user's complete profile including id, username, primaryEmail, profile, and customData.

Create and Update Users

• POST /api/users - Creates new users via email/password, social login, or passwordless methods.
• PATCH /api/users/:userId - Updates mutable fields such as name and username.
• PATCH /api/users/:userId/profile - Modifies profile-specific data including name and avatar.
• PATCH /api/users/:userId/password - Changes user passwords securely.
• PATCH /api/users/:userId/custom-data - Updates the flexible customData JSON field for storing application-specific metadata.
• PATCH /api/users/:userId/is-suspended - Toggles user suspension status.

Delete Users

• DELETE /api/users/:userId - Permanently removes a user account from the system.

Role Assignment

• GET /api/users/:userId/roles - Lists all roles assigned to a specific user.
• POST /api/users/:userId/roles - Assigns one or more roles to a user.
• DELETE /api/users/:userId/roles/:roleId - Removes a specific role assignment.

Session Control

• GET /api/users/:userId/sessions - Lists all active sessions for a user.
• DELETE /api/users/:userId/sessions/:sessionId - Revokes a specific session, effectively logging the user out from that device.

Implementing the TypeScript SDK

The @logto/api package provides type-safe client generation through the createManagementApi factory function located in packages/api/src/management.ts. This helper automatically manages access tokens and generates a fully typed client based on the OpenAPI specification.

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

// Initialise the client with your tenant and M2M credentials
const { apiClient } = createManagementApi('my-tenant-id', {
  clientId: 'my-client-id',
  clientSecret: 'my-client-secret',
});

// Example: list users with pagination
const response = await apiClient.GET('/api/users', {
  query: { page: 1, limit: 20 },
});

console.log('Users:', response.data);

For custom token handling scenarios, the SDK also exposes a low-level createApiClient function.

Source Code Architecture

The implementation spans several key files in the logto-io/logto repository:

• packages/api/src/management.ts - Factory function that creates the typed Management API client with automatic client-credential token handling.
• packages/schemas/src/types/user.ts - TypeScript definitions for user entities, defining fields such as id, username, primaryEmail, profile, and customData.
• packages/api/src/generated-types/management.ts - Auto-generated OpenAPI type definitions (paths) describing every Management API endpoint.
• packages/core/src/routes/users.ts - Express route handlers implementing the HTTP interface for user operations.
• packages/core/src/tenants/queries/users.ts - Database query layer interacting with the users table.

Summary

• The Logto API for managing users is a RESTful Management API requiring OAuth 2.0 client credentials authentication.
• Endpoints cover full CRUD operations, role management, and session control under the /api/ base path.
• The @logto/api SDK provides type-safe access through createManagementApi with automatic token management.
• User data structures are defined in packages/schemas/src/types/user.ts, while route logic resides in packages/core/src/routes/users.ts.

Frequently Asked Questions

How do I authenticate requests to the Logto Management API?

You must create an M2M application in the Logto Console, grant it Management API permissions, and use the client ID and secret to obtain an access token via the OAuth 2.0 client credentials flow. The @logto/api SDK handles this automatically when you use createManagementApi.

What user fields can I update through the Management API?

You can update mutable fields including name, username, profile (name, avatar), customData (JSON metadata), and password. The user ID and primary identifiers created during registration typically remain immutable.

Can I manage user roles and permissions via the API?

Yes. The Management API provides dedicated endpoints at /api/users/:userId/roles to list, assign, and remove roles. You can also query active sessions at /api/users/:userId/sessions and revoke specific sessions when necessary.

Is the Logto Management API type-safe?

Yes. The @logto/api package generates a fully typed client based on the OpenAPI specification found in packages/api/src/generated-types/management.ts. This ensures compile-time type checking for all request parameters and response payloads.

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