Logto API Endpoints: Complete Reference for the Open-Source Identity Platform

Logto exposes REST endpoints grouped into OpenID Connect authentication flows, Management API CRUD operations, Experience UI configuration, and well-known OpenAPI specifications, all implemented in the Core package under packages/core/src/routes/.

Logto is an open-source identity infrastructure maintained by logto-io/logto. The Core service exposes a comprehensive set of HTTP endpoints that handle everything from standard OpenID Connect authentication to tenant administration. This guide catalogs the complete Logto API endpoints surface based on the current source code in the repository.

OpenID Connect (OIDC) Authentication Endpoints

The OIDC implementation follows the standard protocol for identity verification. In packages/core/src/routes/authn.ts, Logto registers the standard OpenID Connect discovery and token endpoints.

Core OIDC endpoints include:

• GET /oidc/.well-known/openid-configuration – Returns the OIDC discovery document containing issuer metadata and endpoint locations.
• GET /oidc/.well-known/jwks – Serves the JSON Web Key Set for token signature verification.
• GET /oidc/authorize – Handles authorization requests for the authorization code flow.
• POST /oidc/token – Exchanges authorization codes for access tokens, ID tokens, and refresh tokens.
• POST /oidc/introspect – Provides token introspection capabilities to validate token state.
• POST /oidc/revoke – Revokes active tokens.
• GET /oidc/userinfo – Returns claims about the authenticated end-user.

Management API Endpoints

The Management API provides CRUD operations for tenant resources. All routes are prefixed with /api/ and defined across modular route files in packages/core/src/routes/.

User Management

Implemented in packages/core/src/routes/user.ts:

• GET /api/users – List users with pagination and filtering.
• POST /api/users – Create a new user record.
• GET /api/users/:id – Retrieve a specific user by ID.
• PATCH /api/users/:id – Update user attributes.
• DELETE /api/users/:id – Remove a user from the system.

Application Management

Defined in packages/core/src/routes/application.ts:

• GET /api/applications – List registered applications.
• POST /api/applications – Register a new application/client.
• GET /api/applications/:id – Get application details including client credentials.
• PATCH /api/applications/:id – Update application configuration.
• DELETE /api/applications/:id – Delete an application.

Resources and Roles

API resources and RBAC are handled in packages/core/src/routes/resource.ts and packages/core/src/routes/role.ts:

• GET /api/resources – List API resources (protected resource indicators).
• POST /api/resources – Create a new API resource.
• GET /api/roles – List system roles.
• POST /api/roles – Create a custom role.
• GET /api/role-permissions/:roleId – Retrieve permission mappings for a specific role.

Well-Known and OpenAPI Documentation

Logto exposes machine-readable API specifications via the /.well-known/ path. The generation logic resides in packages/core/src/routes/well-known/well-known.openapi.ts.

Documentation endpoints:

• GET /.well-known/management.openapi.json – Complete OpenAPI specification for the Management API.
• GET /.well-known/experience.openapi.json – Specification for the Experience (sign-in) API.
• GET /.well-known/user.openapi.json – OpenAPI spec for user-focused endpoints.

Experience (Sign-In UI) API

These endpoints support the frontend Sign-In Experience SPA:

• GET /experience/experience-config – Returns the current sign-in UI configuration, including branding and flow settings.
• GET /experience/social-redirect-fallback – Handles fallback routing when social login redirects fail.

Connector, SSO, and Verification Endpoints

Social and SSO Connectors

• GET /api/connectors – List available social connectors (GitHub, Google, etc.).
• POST /api/connectors – Add a new social connector configuration.
• GET /api/sso-connectors – List enterprise SSO connectors (SAML/OIDC).
• POST /api/sso-connectors – Register a new SSO connector.
• GET /api/jit-provisioning/:domain – Just-in-time provisioning configuration for email domains.

Verification and MFA

Implemented in packages/core/src/routes/verification-code.ts and MFA-related routes:

• POST /api/verification-codes – Send email or SMS verification codes.
• POST /api/mfa/verify – Verify MFA challenges (TOTP, WebAuthn).
• POST /api/mfa/backup-codes – Validate backup codes for account recovery.

System Health and Configuration

Operational Endpoints

Defined in packages/core/src/routes/status.ts:

• GET /status – Health check endpoint returning HTTP 204 when the service is operational.
• GET /log – Retrieve recent server logs (admin-only).

One-Time Tokens

Implemented in packages/core/src/routes/one-time-tokens.ts:

• POST /api/one-time-tokens – Generate short-lived tokens for password reset or email verification.
• GET /api/one-time-tokens/:token – Validate and retrieve token metadata.

Logto Config and Hooks

The packages/core/src/routes/logto-config/index.ts file handles advanced configuration:

• GET /api/logto-config/jwt-customizer – Retrieve JWT customizer configuration.
• POST /api/logto-config/inline-hook – Register inline hooks for extending authentication flows.
• GET /secret/:name – Access named secrets (admin-only).

Practical Usage Examples

Below are runnable JavaScript examples using the native fetch API. Replace BASE_URL with your Logto Core address (e.g., https://localhost:3001).

// Retrieve OIDC discovery document
const oidcConfig = await fetch(`${BASE_URL}/oidc/.well-known/openid-configuration`)
  .then(r => r.json());
console.log('Issuer:', oidcConfig.issuer);

// Exchange authorization code for tokens
const tokens = await fetch(`${BASE_URL}/oidc/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authCode,
    redirect_uri: REDIRECT_URI,
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET
  })
}).then(r => r.json());

// List users via Management API (requires admin:read scope)
const users = await fetch(`${BASE_URL}/api/users`, {
  headers: { Authorization: `Bearer ${ADMIN_ACCESS_TOKEN}` }
}).then(r => r.json());

// Send verification code
await fetch(`${BASE_URL}/api/verification-codes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    type: 'email'
  })
});

Summary

• OIDC endpoints in packages/core/src/routes/authn.ts handle standard authentication flows including discovery, authorization, token exchange, and userinfo.
• Management API routes in packages/core/src/routes/ (user.ts, application.ts, resource.ts, role.ts) provide CRUD operations for /api/users, /api/applications, /api/resources, and /api/roles.
• Well-known endpoints generated by packages/core/src/routes/well-known/well-known.openapi.ts serve OpenAPI specifications at /.well-known/*.openapi.json.
• Experience API supports the Sign-In UI configuration at /experience/experience-config.
• System endpoints include health checks at /status and one-time token management in packages/core/src/routes/one-time-tokens.ts.

Frequently Asked Questions

What is the base URL for Logto API endpoints?

Logto Core typically runs on port 3001 by default. The base URL structure separates concerns: OIDC endpoints use /oidc/, Management APIs use /api/, and well-known documents use /.well-known/. For example, https://your-logto-domain.com/api/users accesses the user management endpoint.

How do I authenticate requests to the Management API?

Management API endpoints require a valid access token with appropriate scopes (e.g., admin:read or admin:write). Obtain this token by requesting the management-api resource during the OIDC token flow, or generate a Machine-to-Machine (M2M) token using the client credentials grant against /oidc/token.

Where can I find the complete OpenAPI specification for Logto?

Access the dynamically generated specification at /.well-known/management.openapi.json on your Logto Core instance. This JSON document includes all available endpoints, request schemas, and response formats. The generation logic is implemented in packages/core/src/routes/well-known/well-known.openapi.ts.

What is the difference between OIDC endpoints and Management API endpoints?

OIDC endpoints (under /oidc/) implement the OpenID Connect protocol for end-user authentication and token issuance, following industry standards. Management API endpoints (under /api/) are Logto-specific administrative interfaces for configuring users, applications, roles, and tenant settings, requiring separate authorization.

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