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** ```mermaid graph LR CI(Continuous integration job) <-->|Create a new user| L(Logto Management API) ``` **Service communication** ```mermaid graph LR B(Backend service) <-->|Search users| L(Logto Management API) ``` **Single page app** ```mermaid graph LR F(Frontend) -->|1 List orders| B(Backend service) B <-->|2 Find orders| D(Database) B <-->|3 Search users related to orders| L(Logto Management API) B -->|4 Combined response| F ``` **Web server that renders HTML** ```mermaid graph LR W(Web server) <-->|Search users| L(Logto Management API) ``` ## 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: ```mermaid graph LR B(Backend service) <-->|Using client credentials| L(Logto Management API) ``` **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: ```mermaid graph LR S(Single page app) -->|Request with access token| B(Backend service) <-->|Using client credentials| L(Logto Management API) B -->|Response with data| S ``` 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. Currently Logto Management API only has one permission all that allows all operations. We are working on adding more granular permissions. ### Get access token You can follow the steps in [this article](https://docs.logto.io/docs/recipes/integrate-logto/machine-to-machine/) 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: ```mermaid graph LR S(Single page app) --> E(GET /api/top-users) subgraph Backend service E end ``` 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](https://docs.logto.io/docs/recipes/integrate-logto/) into that app. Then you can use the SDK to get the access token and send the request to the endpoint: ```mermaid graph LR S(Single page app) -->|1 Request with access token| E(GET /api/top-users) subgraph Backend service E end ``` 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: ```mermaid graph LR E(GET /api/top-users) <-->|2 Query top 10 users| D(Database) E <-->|3 Get user information by IDs| L(Logto Management API) subgraph Backend service E end ``` Finally, you can return the response to the single page app: ```mermaid graph LR E(GET /api/top-users) -->|4 Return combined response| S(Single page app) subgraph Backend service E end ``` A complete sequence diagram: ```mermaid sequenceDiagram participant S as Single page app participant E as GET /api/top-users participant D as Database participant LM as Logto Management API participant L as Logto OIDC S ->> L: User signs in L ->> S: Complete sign in S ->> L: Request access token for backend service (via authorization code or refresh token) L ->> S: Return access token S ->> E: Request with access token E ->> E: Validate access token E ->> D: Query top 10 users D ->> E: Return top 10 users with IDs E ->> L: Request access token for Logto Management API (via client credentials) L ->> E: Return access token E ->> LM: Get top 10 users' information LM ->> E: Return users' information E ->> E: Combine users' information with top 10 users E ->> S: Return combined response ``` 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](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). 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](https://docs.logto.io/docs/recipes/protect-your-api/#validate-the-api-requests-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)](https://docs.logto.io/docs/recipes/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. Try Logto Cloud for free