# Logto API for Managing Users: Complete Management API Reference

> Explore the Logto Management API a powerful M2M REST API for user CRUD operations role assignments and session management secured with OAuth 2.0

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: api-reference
- Published: 2026-06-30

---

**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`](https://github.com/logto-io/logto/blob/main/packages/api/src/management.ts). This helper automatically manages access tokens and generates a fully typed client based on the OpenAPI specification.

```typescript
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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/packages/api/src/generated-types/management.ts)** - Auto-generated OpenAPI type definitions (`paths`) describing every Management API endpoint.
- **[`packages/core/src/routes/users.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes/users.ts)** - Express route handlers implementing the HTTP interface for user operations.
- **[`packages/core/src/tenants/queries/users.ts`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/types/user.ts), while route logic resides in [`packages/core/src/routes/users.ts`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/packages/api/src/generated-types/management.ts). This ensures compile-time type checking for all request parameters and response payloads.