メインコンテンツまでスキップ

Management API との連携

Logto Management API とは？​

Logto Management API は、開発者が自社のプロダクト要件や技術スタックに合わせて実装を完全にコントロールできる包括的な API 群です。これはあらかじめ用意されており、コンソール > API リソース > Logto Management API にリストされています。削除や変更はできません。

識別子は https://[tenant-id].logto.app/api というパターンです。

注記:

Logto Management API の識別子は Logto Cloud と Logto Open Source バージョンで異なります：

  • Logto Cloud: https://[tenant-id].logto.app/api
  • Logto OSS: https://default.logto.app/api

以下の例では Cloud バージョンの識別子を使用します。

Logto Management API リソース Logto Management API 詳細

Logto Management API を利用することで、Logto の堅牢なバックエンドサービスへアクセスできます。これらは高いスケーラビリティを持ち、多様なシナリオで活用可能です。管理コンソールのローコード機能だけでは実現できないことも可能です。

よく使われる API の一部を以下に示します：

利用可能な API について詳しくは https://openapi.logto.io/ をご覧ください。

Logto Management API へのアクセス方法​

M2M アプリの作成​

注記:

M2M (マシン間通信) 認証フローに慣れていない場合は、まず 認証フローの理解 を読んで基本概念を把握することをおすすめします。

コンソール > アプリケーション に移動し、「マシン間通信」アプリケーションタイプを選択して作成を開始します。

M2M アプリ作成プロセス中に、アプリケーションに M2M ロール を割り当てるページに案内されます：

M2M ロール割り当てモーダル

また、すでに M2M アプリが作成されている場合は、M2M アプリの詳細ページでこれらのロールを割り当てることもできます：

M2M ロール割り当てページ

ロール割り当てモジュールでは、すべての M2M ロールが表示されます。Logto アイコンが付いているロールは Logto Management API 権限を含んでいることを示します。

M2M アプリに Logto Management API 権限を含む M2M ロールを割り当てましょう。

アクセストークンの取得​

アクセストークンリクエストの基本​

M2M アプリは、HTTP リクエストエンティティボディで application/x-www-form-urlencoded 形式を使用して次のパラメーターを追加し、トークンエンドポイントに POST リクエストを送信してアクセス トークンを取得します：

  • grant_type: client_credentials に設定する必要があります
  • resource: アクセスしたいリソース
  • scope: アクセスリクエストのスコープ

また、トークンエンドポイントが M2M アプリを認証 (Authentication) するために、リクエストヘッダーに M2M アプリの資格情報を含める必要があります。

これは、リクエストの Authorization ヘッダーに Basic authentication 形式でアプリの資格情報を含めることで実現されます。ここで、ユーザー名は App ID、パスワードは App Secret です。

M2M アプリの詳細ページから App ID と App Secret を見つけることができます：

App ID と App Secret

Logto Management API 用アクセストークンの取得​

Logto には組み込みの「Logto Management API」リソースが用意されています。これは Logto Management API への all 権限を持つ読み取り専用リソースであり、API リソース一覧から確認できます。 リソース API インジケーターは https://{your-tenant-id}.logto.app/api の形式となっており、これはアクセス トークン (Access token) リクエストボディで使用するリソース値となります。

Logto Management API の詳細

Logto Management API へアクセスする前に、M2M アプリにこの組み込み「Logto Management API」リソースの all 権限を含む M2M ロールが割り当てられていることを確認してください。

備考:

Logto では、新しく作成されたテナント向けに事前設定済みの「Logto Management API access」M2M ロールも提供しています。このロールには Logto Management API リソースの all 権限がすでに割り当てられています。権限を手動で設定することなく、そのまま利用できます。この事前設定済みロールは必要に応じて編集・削除も可能です。

それでは、これまでの内容をまとめてリクエストを送信しましょう：

備考:

v1.30.1 以降、Logto 公式の @logto/api Node.js SDK が提供されており、Logto Management API とのやり取りが簡単に行えます。

Logto Cloud​

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// または、アクセス トークン (Access token) の取得を省略して直接 API コールも可能です
const response = await apiClient.GET('/api/users');
console.log(response.data);

セルフホスト / OSS​

OSS ユーザーはテナント ID に default を使用し、baseUrl および apiIndicator の設定も必要です。

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

アクセストークンを使った Logto Management API へのアクセス​

@logto/api SDK を使用すると、以下のコードスニペットで任意の Management API と直接やり取りできます。アクセス トークン (Access token) は内部でキャッシュされ、必要に応じて自動的にリフレッシュされます。

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

Logto Management API の主な利用シナリオ​

開発者は Logto Management API を使って多くの追加機能を実装しています。API は高いスケーラビリティを持ち、幅広いニーズに対応可能です。ここでは、Logto 管理コンソールでは実現できないが、Logto Management API で実現できるシナリオ例をいくつか紹介します。

独自のユーザープロファイル実装​

Logto では現在、ユーザープロファイルのための UI ソリューションは提供していません。ユーザープロファイルはビジネスやプロダクト属性と密接に関係しているためです。最適なアプローチを検討中ですが、API を使って独自にソリューションを構築することを推奨します。たとえば、インタラクション API、プロファイル API、認証コード API などを活用して、要件に合ったカスタムソリューションを開発できます。

Logto 管理コンソールは基本的な検索・フィルタリング機能をサポートしています。あいまい検索、完全一致、大文字小文字の区別などの高度な検索オプションについては、高度なユーザー検索 のチュートリアルやガイドを参照してください。

独自の組織管理実装​

組織 機能を使ってマルチテナントアプリを構築している場合、組織招待やメンバー管理などのタスクに Logto Management API が必要になることがあります。SaaS プロダクトでテナント内に管理者とメンバーがいる場合、Logto Management API を使ってビジネス要件に合わせたカスタム管理ポータルを作成できます。詳細は こちら をご覧ください。

Logto Management API 利用のヒント​

ページネーションされた API レスポンスの管理​

一部の API レスポンスは結果が多くなる場合があり、ページネーションされます。Logto では 2 種類のページネーション情報を提供しています。

ページネーションされたレスポンスヘッダーは次のようになります：

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

リンクヘッダーは、前のページ、次のページ、最初のページ、最後のページの URL を提供します：

  • 前のページの URL には rel="prev" が付きます。
  • 次のページの URL には rel="next" が付きます。
  • 最後のページの URL には rel="last" が付きます。
  • 最初のページの URL には rel="first" が付きます。

total-number ヘッダーの利用​

標準のリンクヘッダーに加え、Logto は Total-Number ヘッダーも追加します：

Total-Number: 216

これによりページ数の表示などが非常に便利になります。

ページ番号とページサイズの変更​

2 つのオプションのクエリパラメーターがあります：

  • page: ページ番号を示します。1 から始まり、デフォルト値は 1 です。
  • page_size: 1 ページあたりのアイテム数を示します。デフォルト値は 20 です。

レートリミット​

注記:

これは Logto Cloud のみの仕様です。

すべてのユーザーに対してサービスの信頼性とセキュリティを確保するため、Web サイトへのトラフィックを監視・管理する一般的なファイアウォールを導入しています。厳密なレートリミットは設けていませんが、保護機能が発動しないよう、10 秒あたり約 200 リクエスト以内に抑えることを推奨します。

Logto Management API の使い方：ステップバイステップガイド

Postman で M2M アクセストークンを数分で取得する