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

While Logto provides a web-based Console for you to manage identities, using Management API is a powerful alternative when you want to automate your workflow or access Logto programmatically. This guide will walk you through the steps to use Logto Management API in different scenarios.

Overview

You may notice there's a built-in API resource "Logto Management API" in Logto Console. It will be the key role in this guide.

Comparing to other API resources, currently Logto Management API does not allow direct access from end-users because it's designed for machine-to-machine communication, and it's so powerful that it can be used to manage your Logto account and resources.

Here are some typical scenarios that you may want to use Logto Management API:

CI/CD

Service communication

Single page app

Web server that renders HTML

Architecture

Regardless of the scenarios, there are two patterns that you can use to access Logto Management API.

Pattern 1: Direct access

In this pattern, your client or service will directly access Logto Management API. In Logto, the client or service is called a "machine-to-machine" app.

An example of using backend service:

Pattern 2: Indirect access

In this pattern, your client or service will access Logto Management API through a backend service. Pattern 2 is built on top of pattern 1, which has another app involved. The new app can be a traditional web, native, or single page app that will access the backend service.

An example of using single page app:

This pattern is useful when you want to have custom logic to control the access to Logto Management API. For example, you may want to return all orders for a consumer, and attach the seller's information to each order. In this case, you can use the single page app to request the backend service to get the orders, and in the backend service, you can use Logto Management API to get the seller's information.

Access Logto Management API

Create a machine-to-machine app

First, you need to create a machine-to-machine app in Logto Console. Head to the "Applications" tab and click "Create application" button. Then click "Start building" in the "Machine-to-machine" card.

Set up a machine-to-machine role

In order to access Logto Management API, you need to create a machine-to-machine role with the proper permissions. In Logto Console, head to the "Roles" tab and click "Create role" button. Click "Show more options" and select "Machine-to-machine app role" in the "Role type" section.

Now you can see the "Logto Management API" shows up in the "Assign permissions" section. Tick the API resource for all permissions, and click "Create role" button.

Once the role is created, you can assign it to the machine-to-machine app you created in the previous step.

Get access token

You can follow the steps in this article to get an access token via client credentials grant for your machine-to-machine app. Test the access token by sending request to an endpoint in Logto Management API.

Now you are ready for pattern 1. Note the access token is valid for a short period of time, so you may want to refresh it periodically if you want to cache it.

Add another layer

Although accessing Logto Management API is not allowed for end-users, you can add another layer to leverage the power of Logto Management API and let it empower your service.

For example, you are building an online community with a single page app and a backend service. You may want to have a feature that allows signed-in users to see the top 10 users who have the most followers. An endpoint GET /api/top-users will be created:

To ensure the endpoint is only accessible by signed-in users, you can create a "single page app" in Logto Console, and integrate Logto SDK into that app. Then you can use the SDK to get the access token and send the request to the endpoint:

In the backend service, you can first query the top 10 users from the database, and then use Logto Management API to get the user's information:

Finally, you can return the response to the single page app:

A complete sequence diagram:

In this flow, it involves two types of access tokens: one for the backend service to access Logto Management API, and the other for the single page app to access the backend service.

The former access token is the one you got in the previous section. The latter access token is the one you can get from Logto SDK.

My access token in the single page app is not a JSON Web Token (JWT)

If you don't specify the resource when calling getAccessToken method in Logto SDKs, the access token will be an opaque string that is intended to be used for the userinfo endpoint. To get a JWT:

1. Define an API resource in Logto Console, e.g. https://api.example.com.
2. Add the API resource to the resources config of Logto SDK, e.g. resources: ['https://api.example.com'].
3. Call getAccessToken method with the API resource, e.g. getAccessToken('https://api.example.com').

To validate the JWT in your backend service, please refer to Validate the API request's authorization token.

What does the JWT in the single page app imply?

The JWT only implies that the user has signed in and tries to access the API resource. It does not imply that the user has specific permissions of the API resource. It's up to you to decide whether to grant the user access to the API resource.

If you need more granular access control, you can also apply role-based access control (RBAC) to the user. See 🔐 Role-based access control (RBAC) for details.

Closing notes

Logto Management API is powerful and flexible for multiple scenarios. With the help of standard protocols, you can easily integrate Logto Management API into your application and build a secure and scalable system. If you have any questions, please feel free to contact us.