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

Management API と対話する

Logto Management API とは？​

Logto Management API は、開発者が製品のニーズや技術スタックに合わせて実装を完全にコントロールできる包括的な API セットです。これは事前に構築され、コンソール > API リソース > Logto Management API にリストされており、削除や変更はできません。

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

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

Logto Management API を使用すると、Logto の強力なバックエンドサービスにアクセスできます。これらは非常にスケーラブルで、多くのシナリオで利用可能です。これは、Admin Console のローコード機能で可能なことを超えています。

以下は、よく使用される API の一部です：

利用可能な API について詳しく知るには、https://openapi.logto.io/ を訪問してください。

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

M2M アプリを作成する​

注記:

M2M (マシン間通信) 認証 (Authentication) フローに慣れていない場合は、基本的な概念を理解するために 認証 (Authentication) フローを理解する を最初に読むことをお勧めします。

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

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

Assign M2M roles modal

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

Assign M2M roles page

ロール割り当てモジュールでは、すべての 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 Admin Console では不可能ですが、Logto Management API を通じて実現できるシナリオの例をいくつか紹介します。

独自のユーザープロフィールを実装する​

Logto は現在、ユーザープロフィールのための事前構築された UI ソリューションを提供していません。ユーザープロフィールはビジネスや製品の属性と密接に関連していることを認識しています。最適なアプローチを決定するために作業を進めている間、API を使用して独自のソリューションを作成することをお勧めします。たとえば、インタラクション API、プロフィール API、検証コード API を利用して、ニーズに合ったカスタムソリューションを開発できます。

Logto Admin Console は基本的な検索とフィルタリング機能をサポートしています。あいまい検索、完全一致、ケースセンシティブなどの高度な検索オプションについては、高度なユーザー検索 のチュートリアルとガイドを確認してください。

独自の組織管理を実装する​

マルチテナントアプリを構築するために 組織 機能を使用している場合、組織の招待やメンバー管理などのタスクに 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" に続きます。

トータルナンバーヘッダーを使用する​

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

Total-Number: 216

これはページ番号を表示するのに非常に便利で役立ちます。

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

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

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

レート制限​

注記:

これは Logto Cloud のみです。

すべてのユーザーに対するサービスの信頼性とセキュリティを確保するために、私たちはウェブサイトへのトラフィックを監視および管理する一般的なファイアウォールを採用しています。厳格なレート制限は設けていませんが、保護措置を発動しないように、ユーザーが 10 秒ごとに約 200 リクエストに活動を制限することをお勧めします。

Logto Management API を使用する：ステップバイステップガイド

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