Skip to main content

Interact with Management API

What is Logto Management API?​

The Logto Management API is a comprehensive set of APIs that gives developers full control over their implementation to suit their product needs and tech stack. It is pre-built, listed in the Console > API resources > Logto Management API, and cannot be deleted or modified.

Its identifier is in the pattern of https://[tenant-id].logto.app/api

Logto Management API Resource Logto Management API Details

With the Logto Management API, you can access Logto's robust backend services, which are highly scalable and can be utilized in a multitude of scenarios. It goes beyond what's possible with the Admin Console's low-code capabilities.

Some frequently used APIs are listed below:

To learn more about the APIs that are available, please visit https://openapi.logto.io/.

How to access Logto Management API​

Create an M2M app​

note:

If you're not familiar with M2M (Machine-to-Machine) authentication flow, we recommend reading Understanding authentication flow first to understand the basic concepts.

Go to Console > Applications, select the "Machine-to-machine" application type and start the creation process.

During the M2M app creation process, you’ll be directed to a page where you can assign M2M roles to your applications:

Assign M2M roles modal

Or you can also assign these roles on the M2M app detail page when you already have an M2M app created:

Assign M2M roles page

In the role assignment module, you can see all M2M roles are included, and roles indicated by a Logto icon means that these roles include Logto Management API permissions.

Now assign M2M roles include Logto Management API permissions for your M2M app.

Fetch an access token​

Basics about access token request​

M2M app makes a POST request to the token endpoint to fetch an access token by adding the following parameters using the application/x-www-form-urlencoded format in the HTTP request entity-body:

  • grant_type: Must be set to client_credentials
  • resource: The resource you want to access
  • scope: The scope of the access request

And you also need to include your M2M app's credentials in the request header for the token endpoint to authenticate your M2M app.

This is achieved by including the app's credentials in the Basic authentication form in the request Authorization header, where username is the App ID, and password is the App Secret.

You can find the App ID and App Secret from your M2M app's details page:

App ID and App Secret

Fetch access token for Logto Management API​

Logto provides a built-in “Logto Management API” resource, it’s a readonly resource with the all permission to access Logto Management API, you can see it from your API resource list. The resource API indicator is in the pattern of https://{your-tenant-id}.logto.app/api , and this will be your resource value used in the access token request body.

Logto Management API details

Before accessing Logto Management API, make sure your M2M app has been assigned with M2M roles that include the all permission from this built-in “Logto Management API” resource.

info:

Logto also provides a pre-configured “Logto Management API access” M2M role for new created tenants, which the Logto Management API resource’s all permission has already assigned to. You can use it directly without manually setting permissions. This pre-configured role can also be edited and deleted as needed.

Now, compose all we have and send the request:

const logtoEndpoint = 'https://your.logto.endpoint'; // Replace with your Logto endpoint
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};
caution:

For Logto Cloud users: when you’re interacting with Logto Management API, you can not use custom domain, use the default Logto endpoint https://{your_tenant_id}.logto.app/oidc/token to grant access tokens.

Access token response​

A successful access response body would be like:

{
  "access_token": "eyJhbG...2g", // Use this token for accessing the Logto Management API
  "expires_in": 3600, // Token expiration in seconds
  "token_type": "Bearer", // Auth type for your request when using the access token
  "scope": "all" // scope `all` for Logto Management API
}
note:

Logto does not currently support the M2M app to represent a user. The sub in the access token payload will be the App ID.

Access Logto Management API using access token​

You may notice the token response has a token_type field, which it's fixed to Bearer.

Thus you should put the access token in the Authorization field of HTTP headers with the Bearer format (Bearer YOUR_TOKEN) when you're interacting with your API resource server.

Using the requested access token with the built-in Logto Management API resource https://[your-tenant-id].logto.app/api to get all applications in Logto:

const logtoEndpoint = 'https://your.logto.endpoint'; // Replace with your Logto endpoint
const accessToken = 'eyJhb...2g'; // Access Token

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

Typical scenarios for using Logto Management API​

Our developers have implemented many additional features using Logto Management API. We believe that our API is highly scalable and can support a wide range of your needs. Here are a few examples of scenarios that are not possible with the Logto Admin Console but can be achieved through the Logto Management API.

Implement user profile on your own​

Logto currently does not provide a pre-built UI solution for user profiles. We recognize that user profiles are closely tied to business and product attributes. While we work on determining the best approach, we suggest using our APIs to create your own solution. For instance, you can utilize our interaction API, profile API, and verification code API to develop a custom solution that meets your needs.

The Logto Admin Console supports basic search and filtering functions. For advanced search options like fuzzy search, exact match, and case sensitivity, check out our Advanced User Search tutorials and guides.

Implement organization management on your own​

If you’re using the organizations feature to build your multi-tenant app, you might need the Logto Management API for tasks like organization invitations and member management. For your SaaS product, where you have both admins and members in the tenant, the Logto Management API can help you create a custom admin portal tailored to your business needs. Check out this for more detail.

Tips for using Logto Management API​

Managing paginated API responses​

Some of the API responses may include many results, the results will be paginated. Logto provides 2 kinds of pagination info.

A paginated response header will be like:

Link: <https://logto.dev/users?page=1&page_size=20>; rel="first"

The link header provides the URL for the previous, next, first, and last page of results:

  • The URL for the previous page is followed by rel="prev".
  • The URL for the next page is followed by rel="next".
  • The URL for the last page is followed by rel="last".
  • The URL for the first page is followed by rel="first".

Using total-number header​

In addition to the standard link headers, Logto will also add a Total-Number header:

Total-Number: 216

That would be very convenient and useful to show page numbers.

Changing page number and page size​

There are 2 optional query parameters:

  • page: indicates the page number, starts from 1, the default value is 1.
  • page_size: indicates the number of items per page, the default value is 20.

Rate limit​

note:

This is only for Logto Cloud.

To ensure the reliability and security of our services for all users, we employ a general firewall that monitors and manages traffic to our website. While we do not enforce a strict rate limit, we recommend that users limit their activity to approximately 200 requests every 10 seconds to avoid triggering our protective measures.

Use Logto Management API: A step-by-step guide

 Obtain M2M access tokens in minutes with Postman