How to Manage Logto Applications via API: Complete CRUD and Configuration Guide

You can fully manage Logto applications programmatically through RESTful Management API endpoints that support creating, reading, updating, and deleting applications, plus managing roles, secrets, custom domains, and user consent scopes using standard HTTP methods with Bearer token authentication.

The Logto identity platform exposes a comprehensive Management API that enables automated application lifecycle management without accessing the admin console. In the logto-io/logto repository, these capabilities are implemented in the core package under packages/core/src/routes/applications, providing granular control over application configuration, security credentials, and access policies.

Application CRUD Operations

The primary application lifecycle endpoints are defined in packages/core/src/routes/applications/application.ts. These routes handle the core CRUD operations for application entities.

Listing and Creating Applications

To retrieve applications, send a GET request to /api/applications. This endpoint supports pagination and filtering by application type (Web, Native, SPA, or MachineToMachine).

// List all applications with pagination
const response = await fetch('https://your-logto-instance.com/api/applications?page=1&page_size=20', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});
const { data: applications } = await response.json();

To create an application, send a POST request to /api/applications with the application type and configuration:

// Create a Machine-to-Machine application
const createResponse = await fetch('https://your-logto-instance.com/api/applications', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Backend Service',
    type: 'MachineToMachine',
    isThirdParty: false,
    oidcClientMetadata: {
      redirectUris: [],
      grantTypes: ['client_credentials'],
    },
  }),
});
const newApp = await createResponse.json();

Retrieving, Updating, and Deleting Applications

Individual application management uses the /:id path parameter. The GET /api/applications/:id endpoint retrieves detailed application configuration, while PATCH /api/applications/:id updates mutable fields including name, logo, redirect URIs, allowTokenExchange, and isThirdParty flags.

// Update application settings
await fetch(`https://your-logto-instance.com/api/applications/${appId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ 
    name: 'Updated App Name',
    allowTokenExchange: true 
  }),
});

To remove an application permanently, send a DELETE request:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://your-logto-instance.com/api/applications/<APP_ID>

Managing Application Roles and Permissions

Application-role associations are handled in packages/core/src/routes/applications/application-role.ts. These endpoints control which RBAC roles are assigned to specific applications.

Assigning and Listing Roles

The GET /api/applications/:id/roles endpoint lists all roles assigned to an application. To assign a new role, send a POST request with the roleId in the request body:

// Assign a role to an application
await fetch(`https://your-logto-instance.com/api/applications/${appId}/roles`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ roleId: 'admin-role-id' }),
});

Revoking Application Roles

To remove a role assignment, use the DELETE /api/applications/:id/roles/:roleId endpoint:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://your-logto-instance.com/api/applications/<APP_ID>/roles/<ROLE_ID>

Handling Application Secrets

For confidential clients such as Machine-to-Machine (M2M) applications, credential management is implemented in packages/core/src/routes/applications/application-secret.ts.

Creating and Listing Secrets

Retrieve existing secrets using GET /api/applications/:id/secrets. Generate new credentials via POST /api/applications/:id/secrets, which returns the generated secret value:

// Create a new application secret
const secretResponse = await fetch(`https://your-logto-instance.com/api/applications/${appId}/secrets`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${adminToken}` },
});
const { value: clientSecret } = await secretResponse.json();
console.log('New secret:', clientSecret); // Store securely - shown only once

Removing Secrets

Delete compromised or unused secrets using DELETE /api/applications/:id/secrets/:secretId:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://your-logto-instance.com/api/applications/<APP_ID>/secrets/<SECRET_ID>

Configuring Protected App Metadata and Custom Domains

Custom domain configuration for protected applications is managed through packages/core/src/routes/applications/application-protected-app-metadata.ts.

To add a custom domain to an application:

curl -X POST \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "auth.example.com"}' \
  https://your-logto-instance.com/api/applications/<APP_ID>/protected-app-metadata/custom-domains

Remove a custom domain using the DELETE method with the domain as a path parameter:

curl -X DELETE \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://your-logto-instance.com/api/applications/<APP_ID>/protected-app-metadata/custom-domains/auth.example.com

Managing User Consent Scopes

User consent and OAuth scope management is handled in packages/core/src/routes/applications/application-user-consent-scope.ts.

List current consent scopes using GET /api/applications/:id/user-consent-scopes. Add scopes via PUT /api/applications/:id/user-consent-scopes/:scopeType/:scopeId, where scopeType identifies the scope category:

// Add a user consent scope
await fetch(
  `https://your-logto-instance.com/api/applications/${appId}/user-consent-scopes/organization-scope/org-read`, 
  {
    method: 'PUT',
    headers: { 'Authorization': `Bearer ${adminToken}` },
  }
);

Remove consent scopes using the DELETE method on the same endpoint path.

API Authentication and Route Registration

All endpoints require a valid admin access token in the Authorization: Bearer <token> header. These routes are registered in packages/core/src/routes/init.ts and documented in the OpenAPI specification at packages/core/src/routes/swagger/openapi.json.

When automating application management, ensure your token has the all scope or specific application management scopes granted through the Logto admin console.

Summary

• Application CRUD endpoints in application.ts provide full lifecycle management via /api/applications with support for filtering, pagination, and type-specific configuration.
• Role management via application-role.ts enables programmatic assignment and revocation of RBAC roles to applications using POST and DELETE methods.
• Secret management in application-secret.ts handles credential rotation for confidential clients, returning generated values only upon creation.
• Custom domains are configured through application-protected-app-metadata.ts using dedicated endpoints for domain addition and removal.
• User consent scopes are managed granularly through application-user-consent-scope.ts with distinct endpoints for different scope types.
• All operations require Bearer token authentication using a valid admin access token with appropriate scopes.

Frequently Asked Questions

What authentication is required to manage Logto applications via API?

You must include a valid admin access token in the Authorization: Bearer <token> header for all requests. Obtain this token through the Logto admin console or via the token endpoint using admin credentials with the all scope. The API validates these tokens in the route handlers defined in packages/core/src/routes/applications.

How do I create a Machine-to-Machine application using the Logto API?

Send a POST request to /api/applications with type: 'MachineToMachine' in the JSON body. You can optionally set isThirdParty: true for external services and specify grantTypes: ['client_credentials'] in the oidcClientMetadata object. The endpoint returns the created application object including the id and initial configuration as implemented in packages/core/src/routes/applications/application.ts.

Can I manage OAuth scopes and user consent settings through the Management API?

Yes. The application-user-consent-scope.ts module exposes endpoints to list, add, and remove consent scopes. Use GET /api/applications/:id/user-consent-scopes to view current permissions, PUT to add scopes using the pattern /:scopeType/:scopeId, and DELETE to remove specific consents. This allows programmatic configuration of what resources users consent to share with applications.

Where are the Logto application API routes registered in the source code?

All application management routes are registered in packages/core/src/routes/init.ts, which imports and mounts the route handlers from packages/core/src/routes/applications/. The individual endpoint logic is split across specialized files: application.ts for CRUD, application-role.ts for permissions, application-secret.ts for credentials, application-protected-app-metadata.ts for domains, and application-user-consent-scope.ts for consent management.

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