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

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 の形式であり、これはアクセス トークンリクエストボディで使用されるリソース値になります。

Logto Management API の詳細

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

備考:

Logto は、新しく作成されたテナントに対して事前に設定された「Logto Management API アクセス」M2M ロールも提供しています。このロールには Logto Management API リソースのすべての権限が既に割り当てられているため、手動で権限を設定することなく直接使用できます。この事前設定されたロールは、必要に応じて編集および削除することもできます。

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

const logtoEndpoint = 'https://your.logto.endpoint'; // あなたの Logto エンドポイントに置き換えてください
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(),
  });
};
注意:

Logto Cloud ユーザー向け：Logto Management API とやり取りする際には、カスタムドメインを使用できません。デフォルトの Logto エンドポイント https://{your_tenant_id}.logto.app/oidc/token を使用してアクセス トークンを取得してください。

アクセス トークンのレスポンス​

正常なアクセスレスポンスボディは次のようになります：

{
  "access_token": "eyJhbG...2g", // Logto Management API へのアクセスにこのトークンを使用します
  "expires_in": 3600, // トークンの有効期限（秒単位）
  "token_type": "Bearer", // アクセス トークン利用時の認証タイプ
  "scope": "all" // Logto Management API 用のスコープ `all`
}
注記:

Logto は現在、M2M アプリがユーザーを表すことをサポートしていません。アクセス トークンのペイロード内の sub はアプリ ID になります。

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

トークンレスポンスには token_type フィールドがあり、これは Bearer に固定されています。

したがって、API リソースサーバーとやり取りする際には、アクセス トークンを HTTP ヘッダーの Authorization フィールドに Bearer 形式（Bearer YOUR_TOKEN）で配置する必要があります。

要求されたアクセス トークンを使用して、Logto のすべてのアプリケーションを取得するために、組み込みの Logto Management API リソース https://[your-tenant-id].logto.app/api を使用します：

const logtoEndpoint = 'https://your.logto.endpoint'; // あなたの Logto エンドポイントに置き換えてください
const accessToken = 'eyJhb...2g'; // アクセス トークン

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

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 アクセス トークンを数分で取得