Grantex

Grantex

オープンソース SDK による AI エージェントの認可と委任アクセス

人間にとっての OAuth 2.0 が、エージェントにとっての Grantex です。

ドキュメント | クイックスタート | リリース JSON | LLM インデックス | 仕様 | IETF ドラフト

所有権： Grantex は Orchestrum Technologies LLP が所有しています。発明者兼所有者：Sanjeev Kumar。お問い合わせ：[email protected] または [email protected]。

ウェブサイト運営者：マーケティングに関するお問い合わせの配信と受諾。

対象を絞った技術パイロットを実施する場合は、セキュリティ制御、 トークンの検証、および OACP の権限境界から始めてください。 AgenticOrg は買い手／売り手のエージェントとワークフローを運用し、Grantex は委任された 権限を管理します。加盟店システムと決済プロバイダーは運用上の権限を保持します。 銀行、フィンテック、または加盟店との連携については、認証情報や非公開の顧客記録を共有せずに、 [email protected] までご相談ください。

Grantex には 2 種類のライセンスがあります。どのディレクトリがどのライセンスを使用するかは、LICENSING.md に記載されています。

• プラットフォーム、無料： 個人が自身の目的（学習、個人的な研究、実験、趣味のプロジェクト）で使用、複製、変更する場合に限ります。組織のために、組織を代表して、または組織の利益のために行動していないことが条件です。
• プラットフォーム、Orchestrum Technologies LLP から事前に書面による許可が必要： 企業、会社、個人事業主の事業、慈善団体、学校、大学、研究機関、政府機関など、組織による、または組織のためのあらゆる利用が対象です。有償か無償かは問いません。評価、テスト、試験運用、内部利用、ホスティングまたは SaaS、再販売、配布、プラットフォームの別製品への組み込みも含まれます。ホスト型サービス（grantex.dev API）の商用利用にも、オープン SDK 経由であっても契約が必要です。COMMERCIAL-LICENSE.md を参照のうえ、[email protected] までお問い合わせください。
• 既存のユーザー： 2026 年 10 月 21 日より前に公開されたリリースは、公開時の条件で引き続き利用できます。同日以降に公開されたプラットフォームのバージョンと更新は対象外のため、組織が利用するには書面による許可が必要です。
• 名称： 「Grantex」と「AgenticOrg」は、Orchestrum Technologies LLP の商標です。Apache ライセンスの SDK や以前のバージョンと併用する場合も含め、名称、ロゴ、ブランドの商用利用には、Orchestrum の事前の書面による承認が必要です。TRADEMARKS.md を参照してください。

Grantex とは？

Grantex は、AI エージェント向けの委任型認可プロトコルとリファレンス実装であり、オープンソースの SDK とソース公開のサーバーを提供します。各エージェントに検証可能な ID と、人間または組織から付与される、対象が限定され、有効期間が定められ、取り消し可能な権限を付与します。また、複数エージェント間の委任、サービス側での検証、監査記録にも対応します。

Grantex は OAuth 2.0 および MCP を補完します。OAuth はアプリケーションとユーザーの認可を処理し、MCP はモデルをツールに接続します。Grantex は、どのエージェントが、どの主体のために、どのアクションを実行できるかを証明します。AI エージェントが人や組織のために行動し、依拠するサービスがそのエージェントに許可された操作の範囲を正確に検証する必要がある場合に、Grantex を使用してください。

AgenticOrg の事業者オンボーディングでは、Grantex の許可証がツールの権限委任を担い、テナント分離、ケースの状態、ケースの目的に関するローカル許可リスト、人によるレビュー、プロバイダー呼び出しの境界は AgenticOrg が担います。最後に検証された AgenticOrg 統合では、トークンレベルのケース目的やケースごとの上限は適用されません。公開済みの Python grantex==0.7.2 には目的と上限の API が含まれていますが、この統合でそれらが使用されているかは検証されていません。ガバナンス対象ケースの統合境界とリリース状況を参照してください。このリポジトリも MCP ツールも、人間に代わってケースを承認する権限をエージェントに付与するものではありません。

エージェント向けプリペイドウォレットと x402 v2

リポジトリのソースには、プリンシパルが管理する AI エージェント向けプリペイドウォレットが含まれています。 プリンシパルは、1 つまたは複数のウォレットを割り当て、割り当て、ウォレット、 エージェント、共有予算グループ、プリンシパル、開発者ごとの制御を適用し、 受取人、リソースのオリジン、アクション、加盟店、目的、プロジェクト、コストセンターを制限し、 人間による正確な承認を必須とし、チャージの頻度を管理し、1 つの割り当て、1 つのウォレット、またはエージェントが利用可能なすべてのウォレットをブロックできます。承認では PostgreSQL 内で値がアトミックに予約され、エージェントの DPoP OAuth ID と、ポリシー評価済みのセマンティックコンテキストにひも付けられます。

@grantex/x402 は、公式の x402 v2 PAYMENT-REQUIRED、 PAYMENT-SIGNATURE、PAYMENT-RESPONSE メッセージを使用します。以前のシミュレートされた X-Payment-Proof の経路は使用されません。sandbox_ledger はエンドツーエンドで実装されています。 外部カストディの記録は、設定済みプロバイダーが資金調達と決済を検証できない限り、意図的にフェイルクローズします。ソースチェックアウトには、ポリシーで署名を制御するオプトインの Base ネイティブ USDC EIP-3009 決済、検証済みの資金調達、永続的な署名リトライ、確定済みチェーンとの照合が含まれるようになりました。Python 0.7.2 と Go v0.4.3 は EVM のレスポンス API と照合 API を公開しますが、どちらも自動 HTTP 決済ラッパーは追加しません。公開済みの TypeScript 0.8.2 と x402 0.4.1 には、オプトインの自動 Base 402／署名／リトライフローが含まれています。4 つのリリースすべてがレジストリで検証済みです。オンチェーンで発行済みの署名はブロックしても取り消せないという制限を含め、Base USDC カストディガイドを参照してください。

import { PrepaidWalletAgentClient } from '@grantex/sdk';
import { createX402Agent } from '@grantex/x402';

const walletAgent = new PrepaidWalletAgentClient({ oauthClient, accessToken });
const x402 = createX402Agent({
  authorizePayment: walletAgent.x402Authorizer,
  // walletId is optional; omit it for policy-based wallet selection.
});

const logicalPaymentId = 'order_01JZ8Y6Q2M4N7P9T';
const response = await x402.fetch('https://merchant.example/paid-resource', {
  // The merchant uses this header to recover a response lost after settlement.
  headers: { 'Idempotency-Key': logicalPaymentId },
  // Grantex uses this option to recover a reservation response lost before settlement.
  idempotencyKey: logicalPaymentId,
});

副作用のあるリソースでは、加盟店は Idempotency-Key に基づいてビジネス上の結果を永続的にキャッシュする必要があります。 Grantex の決済処理は冪等ですが、決済済みの支払い承認は再検証できず、保護対象の処理を二度実行することもできません。

OAuth グラントには wallet:spend と、extra.grantexScope として通知される正確な加盟店アクションスコープを含める必要があります。ウォレットの割り当てポリシーは、その人間が承認した権限を制限できますが、追加することはできません。

Grantex の役割

Grantex は、委任されたエージェント ID、セマンティックな支出ポリシー、複数ウォレット間の予算、正確な承認、アトミックな予約、停止制御、監査を担います。AgenticOrg のデプロイメントまたは別のエージェントランタイムは、オーケストレーションと人間とのやり取りを担います。ウォレット発行者またはカストディアンは、KYC/KYB、AML と制裁への対応、カストディ、ネットワーク承認、MCC／地域／カードの制御、決済、FX、返金、紛争、不正利用、照合について引き続き責任を負います。加盟店は、サーバーが信頼できる価格／支払先データ、注文の冪等性、決済の判定、支払い済み結果の提供について引き続き責任を負います。

責任分担表の全体、ポリシーの組み合わせ、正確な承認プロトコル、残存するギャップの明示的な一覧については、エージェントウォレットのガバナンスを参照してください。

マネージドクライアントは、レジストリ検証済みの @grantex/[email protected]、 @grantex/[email protected]、Python grantex==0.7.2、Go v0.4.3 で実装されています。外部カストディ、プリンシパルへの通知配信、加盟店側の結果の冪等性は、引き続き運用者の責任です。 x402 統合ガイド、ウォレットのライフサイクル、本番運用準備ガイドを参照してください。

セルフホスト型プリペイドウォレットの依存関係

auth-service を実行しても、実際の金銭を扱う製品に必要な依存関係がすべて用意されるわけではありません。セルフホストする運用者は、次の項目を明示的に用意してテストする必要があります。

• 追記専用のウォレット台帳とポリシー判断のための、PostgreSQL マイグレーション 091_agent_prepaid_wallets.sql および 092_layered_wallet_spend_controls.sql、バックアップ、復元、照合作業；
• 正確な OAuth オーディエンスを対象とする HTTPS イングレス。これには /v1/prepaid-wallets と /v1/prepaid-wallets/** が含まれます（オリジンサービスが正常でも、静的ホストが返す 404 によってエージェントのウォレットアクセスが妨げられます）；
• external ウォレットを使用する前に、プロバイダー固有のカストディ、資金調達、決済、Webhook の重複排除、復旧用アダプター。これがない場合、Grantex は意図的に 503 CUSTODY_ADAPTER_UNAVAILABLE を返します；
• プリンシパルにメール、SMS、Slack、WhatsApp、または別の外部チャネルで通知する必要がある場合の、リロードイベント用 SSE/WebSocket 通知ブリッジ。組み込みのウォレットメール配信機能は提供されていません；
• 決済後の副作用に備えた、HTTP Idempotency-Key をキーとする、マーチャント側の永続的な結果キャッシュ；
• 独立したセキュリティ、プロバイダー、照合、インシデント対応、および該当する法務・規制面のレビュー。

サーバーのデプロイと各 SDK のリリースは別々です。レジストリを利用する場合は、リポジトリのマニフェストから利用可能性を推測せず、インストール前に正確なバージョンを確認してください。 本番環境対応ガイドには、ホスティングに関するチェックリスト全体と、メンテナー専用の PowerShell 公開手順書が記載されています。

サプライチェーンとライセンスの管理

セキュリティワークフローでは、追跡対象のすべての npm ロックファイル、追跡対象のすべての Python プロジェクトと requirements の対象範囲、および 3 つすべての Go モジュールを監査します。Dependabot の適用範囲はリポジトリのマニフェストと照合され、外部の GitHub Actions とコンテナーイメージは不変のダイジェストに固定されます。また、レビューされていない npm ライセンス識別子があると CI は失敗します。リリース前に、ローカルで npm run audit:supply-chain と npm run audit:python を実行してください。

Grantex のライセンスが対象とするのは Grantex のソースであり、サードパーティの依存関係ではありません。現在の Sharp/libvips の LGPL および caniuse-lite の CC-BY に関する配布上の注意事項については THIRD_PARTY_NOTICES.mdを、運用者向けチェックリストについては サプライチェーンセキュリティガイドを参照してください。この一覧はエンジニアリング上の管理策であり、法的な非侵害意見ではありません。配布者は、実際に出荷する成果物を確認する必要があります。

OAuth Agent Grants Profile

ホスト型認証サービスとリポジトリの TypeScript クライアントは、候補版 draft-mishra-oauth-agent-grants-03 の3つのロールを実装しています。テスト済みのプロファイルでは、PAR、PKCE S256、DPoP の送信者制約、RFC 9207 のレスポンス発行者検証、有効期間5分のアクセストークン、ファミリー内のリプレイ時に失効するローテーション式リフレッシュトークン、リフレッシュレスポンスが失われた場合の300秒間の完全一致リクエスト復旧、期限切れ時にクリーンアップされる AES-256-GCM 暗号化復旧状態、同一リソースへの RFC 8693 による権限縮小、および RFC 7009 による失効が必要です。

検証は、認証サービスのテスト2,138件、TypeScript SDK のテスト456件、および23の Docker E2E ファイルを順次実行したテスト255件をもって完了しました。これは、テスト対象となった Grantex の構成に関する自己評価のエビデンスであり、独立した相互運用性認証、OAuth Working Group による採用、または IETF の承認を示すものではありません。更新された OAuthAgentClient は、レジストリで検証済みの @grantex/[email protected] として公開されています。

改訂版 -02 が、現在 Datatracker で公開されている版です。候補版 -03 は2026-09-09より前にアップロードしてはならず、予定されている最終レビュー後に改めて明示的な承認が必要です。

Open Agentic Commerce Protocol (OACP) の権限

Open Agentic Commerce Protocol (OACP) は、Grantex のエージェント型コマースにおける信頼およびアーティファクト権限のレイヤーです。Grantex は、OACP のポリシー、署名付きアーティファクトと委任権限の発行または拒否、検証、および互換性アダプターを管理します。AgenticOrg は、購入者と販売者の AI エージェントのランタイム、加盟店向けセルフサービスのオンボーディング、Shopify コネクターのランタイム、将来の加盟店コネクターのセットアップ意図、購入者セッション、チャネルブリッジ、OACP キャッシュ、およびプロバイダーが管理する機能検証を担います。

Shopify、将来の WooCommerce／ERP ソース、POS システムなどの加盟店システムとプロバイダーシステムは、引き続き記録の正本です。プロバイダー、銀行、POS、および決済レールが、委任権限、決済、店頭での処理を担います。Grantex はアーティファクトに署名して検証しますが、加盟店コネクターのランタイムでも、購入者と販売者のすべてのメッセージに対する通行料徴収所でもありません。

flowchart LR
  merchant[Shopify, future ERP/WooCommerce, POS, provider systems] --> agentic[AgenticOrg buyer and seller runtime]
  agentic -->|redacted authority request| grantex[Grantex OACP authority]
  grantex -->|ES256-signed OACP artifacts or blockers| agentic
  agentic --> buyer[Buyer surfaces]
  agentic -->|capability check or handoff| provider[Pine Labs Plural/P3P, bank/POS/provider rails]

エージェント信頼レジストリ：認定発行者とエージェントパスポート

レジストリを使うと、加盟店、決済サービスプロバイダー、API などの依拠当事者が、AI エージェントの動作前にそのエージェントを確認できます。レジストリが答えるのは、エージェントがどのソフトウェアなのか、どの鍵を保持しているのか、どの認定発行者がそのエージェントを保証しているのか、という3つの質問です。回答は、エージェント自身による申告ではなく、算出された信頼レベルとして返されます。付与情報はエージェントが実行できる操作を示し、パスポートはエージェントの身元を示します。パスポートと付与情報を参照してください。

既存のパスにおける新しい動作は、デフォルトで無効になっています。デプロイごとに有効化してください。

• REGISTRY_PUBLIC_ENDPOINTS_ENABLED は、認証不要の読み取りエンドポイント（発行者リスト、ステータスリスト、API キー不要の検索、マニフェスト）を提供します。
• PASSPORT_BOUND_GRANTS_ENABLED は、パスポートに紐づく付与情報を有効にします。
• AGENT_KEY_HISTORY_MIRROR_ENABLED を設定すると、POST と PATCH /v1/agents がエージェントの鍵を鍵の履歴に書き込み、侵害された鍵や別のエージェントに属する鍵を拒否します。
• REGISTRY_ATTESTATION_EDDSA_ENABLED は、ES256 に加えて EdDSA による証明を受け入れます。

セルフホストには、すべての変数が記載されています。対象者別のガイド：

• 認定発行者になる
• エージェントを登録する：プロバイダー向け
• エージェントを検証する：依拠当事者向け

仕様は、レジストリフェデレーション、証明、エージェントキー、エージェントパスポート 1.0、パスポートの紐づけ、検証です。認定発行者が発行する SD-JWT VC であるこのエージェントパスポートは、下記で説明する MPP の AgentPassportCredential とは別のものです。

デモ：開発者によるオプトインの証明

make demo-attest を実行すると、外部関係者を介さず、リポジトリのモック認定発行者を使って登録フローを最初から最後まで実行します。エージェントを登録し、その鍵を証明し、発行者アダプターの境界を介して証明をリクエストし、公開ルックアップでレベルが attested と表示されることを確認した後、発行者で失効させてレベルが下がることを確認します。続けて make demo-verify を実行すると、パスポートに紐づいたグラント、依拠当事者の verify() が成功すること、発行者が失効させると verify() が拒否すること、そして検証器の敵対的フィクスチャがすべて拒否されることまで確認できます。各ステップには live（レジストリ）、fixture（モック発行者）、verifier のいずれかが表示されます。モック発行者の実行およびエージェントの検証を参照してください。

現在のリリース

Grantex の各コンポーネントは個別にバージョン管理されています。プロトコル仕様は引き続き v1.0 Final です。SDK、MCP パッケージ、ロードマップのマイルストーンのバージョンはそれぞれ別のリリース系列であり、モノレポ全体のバージョンを示すものではありません。

以下の公開リリースは 2026-10-04 に検証されました。リポジトリ上のバージョンは、対応するレジストリで公開が確認されるまでリリース候補です。

現在のリリースは、TypeScript 0.8.2、Python 0.7.2、Go v0.4.3、CLI 0.4.2、ゲートウェイ 0.3.0、MCP Auth 4.1.0 です。アップグレードの前に、移行ガイドをすべて確認してください。Node.js の要件、オーディエンスのバインディング、上限付き呼び出しの金額、オンライン失効のデフォルト設定は、破壊的変更です。

TypeScript 0.8.2 と Python 0.7.2 には、サービス側の enforce() によるオーディエンスのバインディング、信頼できる金額がない上限付き呼び出しの拒否、デフォルトでのオンライン失効が含まれます。オーディエンスにバインドした認可の前にエージェントのリソースサーバーを登録し、サービス境界で意図したオーディエンスを設定し、上限付き呼び出しごとに検証済みの金額を指定してください。オフライン検証だけでは現在の失効状態を証明できません。インテグレーションでは、現在の状態を使った強制処理を明示的に組み込む必要があります。変更された npm パッケージには Node.js 22.12 以降が必要です。リリースの制限事項を参照してください。

10 月 4 日の npm および PyPI の成果物は、検証済みの CI アーカイブと一致します。Go タグは公開プロキシ経由で解決され、ダウンロードしたモジュールはテストと vet に合格しました。クリーンな Python SDK のインストールもワークステーションで検証済みです。以前の Docker テストは、過去の検証レポートに記載されたバージョンに適用されます。

デプロイの責任： MCP Auth 4.1.0 は、永続的な共有ストレージ、レンダリングされた同意画面、および修正されたコードの受け渡しに対応しています。本番環境で使用する前に、共有状態、リソースのオーディエンス、ホストによって認証された必須の人間プリンシパルリゾルバー、および信頼できる現在の許可の検証を設定してください。同意画面だけでは、人間を認証したりパスキーを発行したりすることはできません。リリース状況ガイドを参照してください。

リポジトリの開発状況： 認証サービスは、標準の認証プラグインが処理する API キールートにおいて、Redis を利用した Free／Pro／Enterprise の開発者向けレート制限を、それぞれ毎分 100／500／2,000 リクエストに適用します。取り消しと緊急停止にはそれぞれ独自の上限があり、失効フィードとステータスの読み取りにも独自の上限があります。カスタム認証のクォータポリシーは未確定であり、マネージドサービスの展開は SDK の公開とは独立して進められます。

レジストリの最新リリースをインストールするには、バージョン固定を省略してください。リリース状況のドキュメント、パッケージの完全な対応表についてはCOMPATIBILITY.md、リリースノートについてはCHANGELOG.mdを参照してください。

• @grantex/gemma：オフライン同意バンドルとオンデバイス検証の例
• MCP 認可サーバー（@grantex/mcp-auth）：永続ストレージアダプター、レンダリングされた同意画面、認証済み人間プリンシパルの解決、リソースバインディング、現在の許可の検証に対応する OAuth 2.1 + PKCE エンドポイント。バージョン 4 ではホスト認証の設定が必要です
• MCP ツールサーバー（@grantex/mcp）：MCP クライアント向けのエージェント用 Grantex ツール
• @grantex/dpdp：DPDP Act 2023 および EU AI Act の制御マッピング
• Trust Registry：公開 DID 検証レジストリ — grantex.dev/registry
• grantex verify：トークン検査 CLI — アカウントは不要です
• エージェント CLI スキル：Hermes、OpenClaw、およびポータブルな Agent Skills クライアント向けの、ワンコマンドによる SKILL.md のインストール
• 異常検知：実装済みの SQL ベースのチェック 4 種、ライフサイクル API、保存されたルール／チャネル設定。通知の配信にはホスト側のワーカーが必要です

SDK クイックスタート

実行権限と人間のアイデンティティ

署名の検証だけでは、現在の権限を確立することも、実行するエージェントが認証済みの人間に属することを証明することもできません。公開済みの TypeScript SDK 0.8.1 では、呼び出しごとの発行者チェックと、信頼できるプリンシパル／エージェントのバインディングがオプションとして追加されました。Python、Go、および変更された実行インテグレーションも公開済みです。既存のオフライン時のデフォルトは変更されていません。人間の認証と有効な同意は、引き続き発行者／ホストの責任です。アクションに紐づく判定と累積支出制御は、有効な JWT から推測するのではなく、実際の実行入力を使用して適用する必要があります。設定、パッケージの境界、リリース要件については、SDK の実行権限を参照してください。

npm install @grantex/[email protected]

import { Grantex, verifyGrantToken } from '@grantex/sdk';
const gx = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// 1. Register an agent, then request authorization from a user
const agent = await gx.agents.register({
  name: 'quickstart-agent',
  description: 'Grantex quickstart agent',
  scopes: ['calendar:read', 'email:send'],
});
const auth = await gx.authorize({
  agentId: agent.id,
  userId: 'user-456',
  scopes: ['calendar:read', 'email:send'],
});

// Live mode requires consent at this URL and returns the code to your callback.
// Sandbox or policy auto-approval can return the code immediately.
if (!auth.code) {
  console.log(`Approve access at: ${auth.consentUrl}`);
} else {
  // 2. Exchange the authorization code for a scoped, signed JWT
  const { grantToken } = await gx.tokens.exchange({ code: auth.code, agentId: agent.id });

  // 3. Verify locally using the issuer's published JWKS
  const grant = await verifyGrantToken(grantToken, {
    jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  });
  console.log(grant.scopes); // ['calendar:read', 'email:send']
}

python -m pip install grantex==0.7.2               # Python SDK
go get github.com/mishrasanjeev/[email protected] # Go SDK (Go 1.26.1+)
npm install @grantex/[email protected] @grantex/[email protected] # MCP endpoint authorization
npm install -g @grantex/[email protected]                   # Optional CLI tooling

Hermes、OpenClaw、およびあらゆるエージェント CLI

シェルを使用できるエージェントは、エージェント固有の SDK を必要とせず、同じ JSON ファーストの CLI を使用します。

npm install -g @grantex/[email protected]
grantex agent install --target openclaw  # writes ./skills
grantex agent install --target hermes    # writes ~/.hermes/skills/grantex
grantex agent install --target portable  # writes ./.agents/skills

このバンドルは、委任認可の操作用に use-grantex-cli を、サービス境界の実装作業用に integrate-grantex をインストールします。別のホストを使用する場合は、grantex agent install --dir /path/to/skills を使用してください。トークン入力には --env、--file、または --stdin を優先し、最終的な適用処理は保護されたサービス内にとどめてください。

35 個のパッケージを TypeScript、Python、Go で提供しています。Anthropic SDK、LangChain、OpenAI Agents SDK、Google ADK、Strands Agents SDK、CrewAI、Vercel AI、AutoGen、MCP、Express.js、FastAPI、および Terraform とのインテグレーションがあります。バージョンについては互換性マトリックスを、リリースノートについては変更履歴を、現在の CI 状況については GitHub Actions を参照してください。SDK は Apache-2.0 ライセンスです。セルフホスト可能なサーバーは Orchestrum Personal Use License 1.0 の下で提供され、すべての組織には書面による許可が必要です（ライセンスを参照）。新しい relying-party Python 検証ツールは引き続き非公開ソースであり、レジストリにはリリースされていません。

課題

AI エージェントは、実在する人々に代わって、旅行を予約し、メールを送信し、コードをデプロイし、支出しています。しかし：

• スコープ設定がない — エージェントはキーの所有者と同じアクセス権を得ます
• 同意がない — ユーザーがエージェントに許可する操作を承認することはありません
• エージェントごとの ID がない — キーが使用されたことは分かっても、どのエージェントが何のために使ったのかは分かりません
• 失効範囲を細かく制御できない — 1 つのエージェントが不正な動作をすると、キーをローテーションしてすべてを停止することになります
• 委任を制御できない — エージェント A がエージェント B を呼び出す場合、認証情報をコピーして貼り付けます
• 支出制限がない — クラウド API キーを持つエージェントは、リソースを無制限にプロビジョニングできます

OAuth と IAM は不可欠な基盤を提供しますが、多くのエージェントのデプロイでは、個々のエージェントを識別したり、委任された権限を表現したりしない共有認証情報に依存しています。

仕組み

クイックスタート

1. エージェントを登録する

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const agent = await grantex.agents.register({
  name: 'travel-booker',
  description: 'Books flights and hotels on behalf of users',
  scopes: ['calendar:read', 'payments:initiate:max_500', 'email:send'],
});

console.log(agent.did);
// → did:grantex:ag_01HXYZ123abc...

2. ユーザーに認可をリクエストする

const authRequest = await grantex.authorize({
  agentId: agent.id,
  userId: 'user_abc123',       // your app's user identifier
  scopes: ['calendar:read', 'payments:initiate:max_500'],
  expiresIn: '24h',
  redirectUri: 'https://yourapp.com/auth/callback',
});

// Redirect user to authRequest.consentUrl
// Grantex handles the consent UI — plain language, mobile-first
console.log(authRequest.consentUrl);
// → https://consent.grantex.dev/authorize?req=eyJ...

3. 認可コードをグラントトークンと交換する

// After user approves, your redirectUri receives a `code`.
// Exchange it for a signed grant token (RS256 JWT):
const token = await grantex.tokens.exchange({
  code,                  // from the redirect callback
  agentId: agent.id,
});

console.log(token.grantToken);  // RS256 JWT — pass this to your agent
console.log(token.scopes);      // ['calendar:read', 'payments:initiate:max_500']
console.log(token.grantId);     // 'grnt_01HXYZ...'
console.log(token.refreshToken); // store securely for active-grant rotation

リフレッシュトークンは 1 回のみ使用でき、承認されたリフレッシュのたびにローテーションされます。サーバーでのコミット後にリフレッシュ HTTP レスポンスが失われた場合は、直前に使用したリフレッシュトークンをすぐに再試行してください。Grantex は、ローテーション済みのトークンペアを 5 分間（300 秒）復元できます。リフレッシュによって token.expiresAt が延長されることはありません。グラントの有効期限が切れたら、新しい認可リクエストを開始してください。

4. トークンを検証して使用する

// Verify locally after retrieving the issuer's published JWKS
import { verifyGrantToken } from '@grantex/sdk';

const grant = await verifyGrantToken(token.grantToken, {
  jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  requiredScopes: ['calendar:read'],
});
console.log(grant.principalId); // 'user_abc123'
console.log(grant.scopes);     // ['calendar:read', 'payments:initiate:max_500']

// Pass to your agent — it's now authorized
await travelAgent.run({ grantToken: token.grantToken, task: 'Book cheapest flight to Delhi on March 1' });

5. 実行境界でアクションを記録する

// At the trusted execution boundary: explicitly record the outcome
await grantex.audit.log({
  agentId: agent.id,
  agentDid: agent.did,
  grantId: token.grantId,
  principalId: authRequest.principalId,
  action: 'payment.initiated',
  status: 'success',
  metadata: { amount: 420, currency: 'USD', merchant: 'Air India' },
});

6. トークンを検証する（サービス側）

// In any service that receives agent requests — no Grantex account needed
import { verifyGrantToken } from '@grantex/sdk';

const grant = await verifyGrantToken(token.grantToken, {
  jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  requiredScopes: ['payments:initiate'],
});
// Throws if the token is expired, tampered with, has invalid claims, or lacks required scopes.
// Use grantex.tokens.verify(token.grantToken) when you also need current revocation status.

7. ユーザーが自分の権限を管理できるようにする

// Generate a short-lived link for the end-user to view & revoke agent access
const session = await grantex.principalSessions.create({
  principalId: 'user_abc123',
  expiresIn: '2h',
});
// Send session.dashboardUrl to the user via email, in-app notification, etc.
// The short-lived session token is carried in the URL fragment, not the query string.

Python SDK

import os

from grantex import Grantex, AuthorizeParams, ExchangeTokenParams

client = Grantex(api_key=os.environ["GRANTEX_API_KEY"])

# Register agent
agent = client.agents.register(
    name="finance-agent",
    scopes=["transactions:read", "payments:initiate:max_100"],
)

# Authorize a user
auth = client.authorize(AuthorizeParams(
    agent_id=agent.id,
    user_id="user_abc123",
    scopes=["transactions:read", "payments:initiate:max_100"],
))
# Redirect user to auth.consent_url — they approve in plain language

# Exchange the authorization code for a grant token
token = client.tokens.exchange(ExchangeTokenParams(code=code, agent_id=agent.id))

# Verify locally after retrieving the issuer's published JWKS
from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(token.grant_token, VerifyGrantTokenOptions(
    jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
))
print(grant.scopes)  # ('transactions:read', 'payments:initiate:max_100')

# Log an action
client.audit.log(
    agent_id=agent.id,
    agent_did=agent.did,
    grant_id=token.grant_id,
    principal_id=auth.principal_id,
    action="transaction.read",
    status="success",
    metadata={"account_last4": "4242"},
)

グラントトークン

Grantex トークンは、エージェント固有のクレームを拡張した標準的な JWT（RS256）です。どのサービスでも、発行者が公開している JWKS を使って署名をローカルで検証できます。提供されている検証機能は、設定された JWKS URL からこれらのキーを取得するため、アプリケーションではネットワークの可用性、キャッシュ、キーのローテーションを考慮する必要があります：

{
  "iss": "https://grantex.dev",
  "sub": "user_abc123",
  "agt": "did:grantex:ag_01HXYZ123abc",
  "dev": "org_yourcompany",
  "scp": ["calendar:read", "payments:initiate:max_500"],
  "iat": 1709000000,
  "exp": 1709086400,
  "jti": "tok_01HXYZ987xyz",
  "grnt": "grnt_01HXYZ456def"
}

委任クレーム（サブエージェントのトークンに含まれます）：

マルチエージェント委任

Grantex は、ルートエージェントがより狭いスコープを持つサブエージェントを起動するマルチエージェントパイプラインをサポートしています。サブエージェントのトークンには、どのサービスからも確認できる完全な委任チェーンが含まれます。

// Root agent has a grant for ['calendar:read', 'calendar:write', 'email:send']
// It spawns a sub-agent that only needs calendar read access

const delegated = await grantex.grants.delegate({
  parentGrantToken: rootGrantToken,   // root agent's token
  subAgentId: subAgent.id,            // sub-agent to authorize
  scopes: ['calendar:read'],          // must be ⊆ parent scopes
  expiresIn: '1h',                    // capped at parent token's expiry
});

// delegated.grantToken is a fully signed JWT with:
//   parentAgt, parentGrnt, delegationDepth = 1

# Python equivalent
delegated = grantex.grants.delegate(
    parent_grant_token=root_grant_token,
    sub_agent_id=sub_agent.id,
    scopes=["calendar:read"],
    expires_in="1h",
)

プロトコルによって適用される制約：

• サブエージェントのスコープは、親のスコープの厳密な部分集合である必要があります — スコープの昇格は 400 で拒否されます
• サブエージェントのトークン有効期限は min(parent expiry, requested expiry) です — サブエージェントの有効期限が親の有効期限を超えることはありません
• ルートグラントを失効させると、すべての子孫グラントもアトミックに失効します

高度な機能

// Create an OIDC connection
const conn = await grantex.sso.createConnection({
  name: 'Okta Production',
  protocol: 'oidc',
  issuerUrl: 'https://mycompany.okta.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  domains: ['mycompany.com'],
  jitProvisioning: true,
  groupAttribute: 'groups',
  groupMappings: { Engineering: ['read', 'write', 'deploy'], Admins: ['admin'] },
  defaultScopes: ['read'],
});

// Create a SAML 2.0 connection
await grantex.sso.createConnection({
  name: 'Azure AD SAML',
  protocol: 'saml',
  idpEntityId: 'https://sts.windows.net/tenant-id/',
  idpSsoUrl: 'https://login.microsoftonline.com/tenant-id/saml2',
  idpCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
  spEntityId: 'urn:grantex:mycompany',
  spAcsUrl: 'https://myapp.com/sso/callback/saml',
  domains: ['mycompany.com'],
});

// Enforce SSO for the organization
// First complete an OIDC login that maps an administrator to the admin scope.
// The server must have SSO_HUMAN_ENFORCEMENT_ENABLED=true.
await grantex.sso.setEnforcement({ enforce: true });

// Handle OIDC callback with verified ID token
const result = await grantex.sso.handleOidcCallback({ code, state });
console.log(result.email, result.mappedScopes, result.sessionId);
// result.sessionToken is an opaque bearer credential when enabled. Keep it secret.

// List and revoke sessions
const { sessions } = await grantex.sso.listSessions();
await grantex.sso.revokeSession(sessions[0].id);

# Create an OIDC connection
conn = client.sso.create_connection(CreateSsoConnectionParams(
    name="Okta Production",
    protocol="oidc",
    issuer_url="https://mycompany.okta.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
    domains=["mycompany.com"],
    jit_provisioning=True,
    group_attribute="groups",
    group_mappings={"Engineering": ["read", "write", "deploy"]},
))

# Handle OIDC callback
result = client.sso.handle_oidc_callback(SsoOidcCallbackParams(code=code, state=state))
print(result.email, result.mapped_scopes, result.session_id)

# Create a connection
grantex sso connections create --name "Okta" --protocol oidc \
  --issuer-url https://mycompany.okta.com \
  --client-id $CLIENT_ID --client-secret $CLIENT_SECRET \
  --domains mycompany.com --jit-provisioning

# List connections
grantex sso connections list

# Test connectivity
grantex sso connections test sso_01HXYZ...

# Enforce SSO
grantex sso enforce --enable

// Enable FIDO for your developer account
await grantex.updateSettings({ fidoRequired: true, fidoRpName: 'My App' });

// Server-side, after authenticating the end customer:
const { enrollmentUrl } = await grantex.webauthn.createEnrollmentSession({
  principalId: authenticatedCustomer.grantexPrincipalId,
});
// Show the one-use link only to that customer. The hosted page handles WebAuthn.

// List and manage credentials
const { credentials: creds } = await grantex.webauthn.listCredentials('user_abc123');
await grantex.webauthn.deleteCredential(credentialId);

# Enable FIDO for your developer account
from grantex import UpdateDeveloperSettingsParams

client.update_settings(UpdateDeveloperSettingsParams(
    fido_required=True,
    fido_rp_name="My App",
))

# After your app authenticates the customer, issue a one-use hosted link.
session = client.webauthn.create_enrollment_session(principal_id="user_abc123")
enrollment_url = session.enrollment_url

# List and manage credentials
creds = client.webauthn.list_credentials("user_abc123").credentials
client.webauthn.delete_credential(credential_id)

const result = await grantex.tokens.exchange({
  code,
  agentId: agent.id,
  credentialFormat: 'vc-jwt',   // opt-in to VC issuance
});

console.log(result.grantToken);         // standard RS256 JWT (unchanged)
console.log(result.verifiableCredential); // W3C VC-JWT

result = client.tokens.exchange(ExchangeTokenParams(
    code=code,
    agent_id=agent.id,
    credential_format="vc-jwt",
))

print(result.verifiable_credential)  # W3C VC-JWT

const verification = await grantex.credentials.verify(vcJwt);
console.log(verification.valid);
console.log(verification.credentialSubject);
console.log(verification.issuer); // "did:web:grantex.dev"

verification = client.credentials.verify(vc_jwt)
print(verification.valid)
print(verification.credential_subject)

// Check a specific credential's status
const cred = await grantex.credentials.get(credentialId);
console.log(cred.status); // "active" or "revoked"

// List credentials with filters
const { credentials } = await grantex.credentials.list({
  grantId: 'grnt_01HXYZ...',
  status: 'active',
});

curl https://api.grantex.dev/.well-known/did.json

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const passport = await grantex.passports.issue({
  agentId: 'ag_01HXYZ...',
  grantId: 'grnt_01HXYZ...',
  allowedMPPCategories: ['inference', 'compute'],
  maxTransactionAmount: { amount: 50, currency: 'USDC' },
  paymentRails: ['tempo'],
  expiresIn: '24h',
});
// passport.passportId   → "urn:grantex:passport:01HXYZ..."
// passport.encodedCredential → base64url for X-Grantex-Passport header

curl -X POST https://api.grantex.dev/v1/passport/issue \
  -H "Authorization: Bearer $GRANTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "ag_01HXYZ...",
    "grantId": "grnt_01HXYZ...",
    "allowedMPPCategories": ["inference", "compute"],
    "maxTransactionAmount": { "amount": 50, "currency": "USDC" },
    "expiresIn": "24h"
  }'

import { createMppPassportMiddleware } from '@grantex/mpp';

const middleware = createMppPassportMiddleware({ passport });
const enrichedRequest = await middleware(new Request(url, init));
// enrichedRequest now has X-Grantex-Passport header
const response = await fetch(enrichedRequest);

import { verifyPassport } from '@grantex/mpp';

const verified = await verifyPassport(encodedCredential, {
  requiredCategories: ['inference'],
  maxAmount: 10,
});
// verified.humanDID        → "did:grantex:user_alice"
// verified.organizationDID → "did:web:acme.com"
// verified.allowedCategories → ["inference", "compute"]
// verified.maxTransactionAmount → { amount: 50, currency: "USDC" }

import { requireAgentPassport } from '@grantex/mpp';

app.use('/api/inference', requireAgentPassport({
  requiredCategories: ['inference'],
  maxAmount: 10,
}));
// req.agentPassport is populated on valid requests
// 403 with typed error code on invalid requests

MPP の HTTP 402 フローは「Payment」HTTP 認証スキームです。402 応答では WWW-Authenticate: Payment、再試行では Authorization: Payment、成功時には Payment-Receipt を使用します。（PAYMENT-REQUIRED／PAYMENT-SIGNATURE／PAYMENT-RESPONSE は x402 v2 のヘッダーです。）

import { requirePayment } from '@grantex/mpp';

app.get('/api/report', requirePayment({
  secret: process.env.PAYMENT_CHALLENGE_SECRET!,
  realm: 'api.merchant.example',
  offers: () => [{ method: 'tempo', intent: 'charge', request: { amount: '1000', currency: 'usd' } }],
  verifyPayload: async (credential) => verifyWithYourPaymentMethod(credential.payload),
}), handler);
// 402 with WWW-Authenticate challenges; on a valid credential, Payment-Receipt and req.payment

Trust Registry

認証不要で、任意の組織の検証済み信頼レベルを照会できます。

curl https://api.grantex.dev/v1/trust-registry/did:web:grantex.dev
# {"organizationDID":"did:web:grantex.dev","trustLevel":"soc2","domains":["grantex.dev"]}

import { lookupOrgTrust } from '@grantex/mpp';

const record = await lookupOrgTrust('did:web:acme.com');
// record.trustLevel → "verified" | "soc2" | "basic"
// record.verificationMethod → "dns-txt" | "manual" | "soc2"

失効

パスポートを失効させると、サーバー側のステータスがただちに更新されます。ローカルの検証ツールは、オンラインで失効確認を行うか、ステータスデータを更新した後にのみ変更を確認できます。そのため、キャッシュされた結果には反映の遅れが生じる場合があります。

await grantex.passports.revoke('urn:grantex:passport:01HXYZ...');
// Revocation-aware verification rejects after checking refreshed status data

エラーコード

MPP エージェント ID API エンドポイント

パッケージの詳しいドキュメントは packages/mpp/ を参照してください。デモ：grantex.dev/mpp-demo。

const result = await grantex.tokens.exchange({
  code,
  agentId: agent.id,
  credentialFormat: 'sd-jwt',   // opt-in to SD-JWT issuance
});

console.log(result.grantToken);         // standard RS256 JWT (unchanged)
console.log(result.sdJwt);              // SD-JWT with selective disclosure

result = client.tokens.exchange(ExchangeTokenParams(
    code=code,
    agent_id=agent.id,
    credential_format="sd-jwt",
))

print(result.sd_jwt)  # SD-JWT with selective disclosure

const presentation = await grantex.credentials.present({
  sdJwt: result.sdJwt,
  disclosedClaims: ['scopes', 'agentId'],   // only reveal these fields
});

// Send presentation to the verifier — they see scopes and agentId,
// but principalId, developerId, grantId, etc. remain hidden

presentation = client.credentials.present(
    sd_jwt=result.sd_jwt,
    disclosed_claims=["scopes", "agent_id"],
)

// Allocate a budget to a grant
const budget = await grantex.budgets.allocate({
  grantId: 'grnt_01HXYZ...',
  amount: 1000,
  currency: 'USD',
});

// Debit against the budget
const debit = await grantex.budgets.debit({
  grantId: 'grnt_01HXYZ...',
  amount: 42.50,
  description: 'Flight booking',
});
console.log(debit.remaining); // 957.50

// Check the current balance
const balance = await grantex.budgets.balance('grnt_01HXYZ...');
console.log(balance.remainingBudget);

// List all budget transactions for a grant
const { transactions } = await grantex.budgets.transactions('grnt_01HXYZ...');

# Allocate a budget to a grant
budget = client.budgets.allocate(
    grant_id="grnt_01HXYZ...",
    amount=1000,
    currency="USD",
)

# Debit against the budget
debit = client.budgets.debit(
    grant_id="grnt_01HXYZ...",
    amount=42.50,
    description="Flight booking",
)
print(debit.remaining)  # 957.50

# Check the current balance
balance = client.budgets.balance("grnt_01HXYZ...")

# List all budget transactions
transactions = client.budgets.transactions("grnt_01HXYZ...")

// SSE — async generator, automatically reconnects
for await (const event of grantex.events.stream()) {
  console.log(event.type);   // 'grant.created', 'token.issued', etc.
  console.log(event.data);
}

// Convenience wrapper with a callback
grantex.events.subscribe((event) => {
  if (event.type === 'budget.threshold') {
    alert(`Grant ${event.data.grantId} is at ${event.data.percentage}% budget`);
  }
});

# SSE — async generator
async for event in client.events.stream():
    print(event.type)   # 'grant.created', 'grant.revoked', etc.
    print(event.data)

# Convenience wrapper
async def handler(event):
    if event.type == "budget.exhausted":
        await revoke_grant(event.data["grant_id"])

await client.events.subscribe(handler)

// Get current period usage
const usage = await grantex.usage.current();
console.log(usage.tokenExchanges);
console.log(usage.authorizations);
console.log(usage.totalRequests);

// Get usage history over the last 30 days
const { entries } = await grantex.usage.history({ days: 30 });
entries.forEach((e) => console.log(`${e.date}: ${e.totalRequests} requests`));

# Get current period usage
usage = client.usage.current()
print(usage.token_exchanges)
print(usage.total_requests)

# Get usage history over the last 30 days
history = client.usage.history(days=30)
for entry in history.entries:
    print(f"{entry.date}: {entry.total_requests} requests")

// Register a custom domain
const domain = await grantex.domains.create({ domain: 'auth.yourapp.com' });
console.log(domain.verificationToken);
// → Add a DNS TXT record: _grantex-verify.auth.yourapp.com = <token>

// Verify the domain after adding the DNS record
const verified = await grantex.domains.verify(domain.id);
console.log(verified.verified); // true

// List all registered domains
const { domains } = await grantex.domains.list();

// Delete a domain
await grantex.domains.delete(domain.id);

# Register a custom domain
domain = client.domains.create(domain="auth.yourapp.com")
print(domain.verification_token)

# Verify after adding DNS TXT record
verified = client.domains.verify(domain.id)
print(verified.verified)  # True

# List all domains
domains = client.domains.list()

# Delete a domain
client.domains.delete(domain.id)

// Upload a policy bundle
await grantex.policies.sync({
  format: 'opa',           // 'opa' or 'cedar'
  bundle: bundleBuffer,    // policy bundle as Buffer
});

// List policy bundles
const { bundles } = await grantex.policies.bundles();

# Upload a policy bundle
client.policies.sync(
    format="opa",
    bundle=bundle_bytes,
)

# List policy bundles
bundles = client.policies.bundles()

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// Register a consent notice version
const notice = await grantex.dpdp.createConsentNotice({
  noticeId: 'privacy-v1',
  version: '1.0',
  title: 'Data Processing Notice',
  content: 'We process your data for...',
  purposes: [{ code: 'analytics', description: 'Usage analytics' }],
});

// Record consent against an existing, active grant
const record = await grantex.dpdp.createConsentRecord({
  grantId: 'grnt_01HXYZ...',
  dataPrincipalId: '[email protected]',
  purposes: [{ code: 'analytics', description: 'Usage analytics' }],
  consentNoticeId: 'privacy-v1',
  processingExpiresAt: '2027-01-01T00:00:00Z',
});

// Records held about a principal, for an access request (DPDP s.11)
const { records } = await grantex.dpdp.listPrincipalRecords('[email protected]');

// Withdraw consent (s.6(4)); optionally revoke the grant and ask your
// application, by webhook, to delete the data it processed
const withdrawal = await grantex.dpdp.withdrawConsent(record.recordId, {
  reason: 'No longer needed',
  revokeGrant: true,
  deleteProcessedData: true,
});

// Record a grievance (DPDP s.13)
const grievance = await grantex.dpdp.fileGrievance({
  dataPrincipalId: '[email protected]',
  type: 'unauthorized-processing',
  description: 'Data used beyond the consented purpose',
});

// Act on an erasure request (DPDP s.12)
const erasure = await grantex.dpdp.requestErasure('[email protected]');

// Generate a DPDP audit export
const report = await grantex.dpdp.createExport({
  type: 'dpdp-audit',
  dateFrom: '2026-01-01T00:00:00Z',
  dateTo: '2026-04-01T00:00:00Z',
});

# Python SDK
from grantex import CreateConsentRecordParams, Grantex

client = Grantex(api_key="gx_...")

record = client.dpdp.create_consent_record(CreateConsentRecordParams(
    grant_id="grnt_01HXYZ...",
    data_principal_id="[email protected]",
    purposes=[{"code": "analytics", "description": "Usage analytics"}],
    consent_notice_id="privacy-v1",
    processing_expires_at="2027-01-01T00:00:00Z",
))
records = client.dpdp.list_principal_records("[email protected]")
erasure = client.dpdp.request_erasure("[email protected]")

スコープの適用

あらゆるコネクターに対してツールレベルの権限を適用できます。独自のマニフェストを定義するか、用意されている53種類のマニフェストを使用してください。

クイックスタート

from grantex import Grantex, ToolManifest, Permission

grantex = Grantex(api_key="gx_...")

# Define a manifest for any connector — yours, not ours
grantex.load_manifest(ToolManifest(
    connector="my-crm",
    tools={"search": Permission.READ, "create_deal": Permission.WRITE, "delete_account": Permission.DELETE},
))

result = grantex.enforce(grant_token=token, connector="my-crm", tool="delete_account")
# result.allowed = False — "write scope does not permit delete operations"

権限階層

独自のマニフェストを使用： インラインで定義する、JSON ファイルから読み込む、ディレクトリから読み込む、または CLI を使ってソースコードから自動生成できます。 53種類のマニフェストを同梱： Salesforce、HubSpot、Jira、Stripe、SAP、S3、Gmail、Slack、GitHub など、さらに44種類を収録しています。そのまま使用することも、出発点として利用することもできます。

フレームワーク用ヘルパー： wrapTool() は LangChain ツールをラップし、スコープを自動的に適用します。createGrantexTool() は Strands Agents SDK を含む TypeScript エージェントフレームワーク用ヘルパーをカバーします。create_grantex_tool() は Python OpenAI Agents SDK、Google ADK、Strands Agents SDK のツールをカバーします。enforceMiddleware() は Express/Fastify のルートに1行で適用できます。FastAPI では GrantexEnforcer 依存関係を使用します。

詳しいドキュメントは、スコープ適用ガイドをご覧ください。

ローカル開発

リポジトリのインストール、ビルド、テストには Node.js 24 LTS を使用してください。アップグレードされた Vitest 5 ツールチェーンには Node.js 22.12 以降が必要です。このコントリビューター向け要件は、 公開済み SDK のランタイム要件とは別のものです。 チェックイン済みのロックファイルを使用して npm ci を実行し、CONTRIBUTING.md を参照してください。

次の 1 つのコマンドでフルスタックを起動します。

git clone https://github.com/mishrasanjeev/grantex.git
cd grantex
docker compose up --build

API キー 2 つが自動的にシードされます。

Sandbox モードはテスト用に設計されています。Sandbox キーと fidoRequired: false（デフォルト）を使用すると、POST /v1/authorize はレスポンス本文で code を返します — リダイレクトは不要です。代わりに実際の登録および同意の手続きをリハーサルするには、fidoRequired: true を設定します。

# Authorize + get code in one step
curl -s -X POST http://localhost:3001/v1/authorize \
  -H "Authorization: Bearer sandbox-api-key-local" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"<id>","principalId":"test-user","scopes":["calendar:read"]}'
# → { ..., "sandbox": true, "code": "01J..." }

# Exchange immediately for a grant token
curl -s -X POST http://localhost:3001/v1/token \
  -H "Authorization: Bearer sandbox-api-key-local" \
  -H "Content-Type: application/json" \
  -d '{"code":"<code>","agentId":"<id>"}'

開発者ポータルは grantex.dev/dashboard から利用できます — サインアップするか API キーを入力すると、ブラウザーからエージェント、許可、ポリシー、異常、コンプライアンスエクスポート、請求を管理できます。

ライブ同意と不規則な事象に関するアカウント設定： Billing ページには、アカウントの実際のプランが表示されます。ソースの上限は Free が有効な許可 1,000 件、Pro が 50,000 件、Enterprise が無制限で、エージェントごとではなく開発者アカウント全体で数えられます。認証済みの GET /v1/billing/subscription でデプロイ済みアカウントを確認してください。エージェント ID だけでは、そのプランは特定できません。Irregularities ページでは、IRREGULARITY_RESPONSE_POLICY_ENABLED=true の場合に POST /v1/anomalies/detect で検出された事象に対し、アカウント全体に適用される alert_only 応答を設定できます。このサーバーフラグがない場合、検出器は重大または深刻な検出結果に対して、有効な許可をエージェント全体で取り消す従来の動作を維持します。Alert-only はアラートを保持し、手動での取り消しや独立したセキュリティゲートを迂回するものではありません。セットアップガイド を参照してください。サーバーの利用可否はデプロイとロールアウトのフラグによって異なります。TypeScript @grantex/[email protected]、Python grantex==0.7.2、Go v0.4.3 では、クライアントメソッドが公開されています。

ローカル開発では、認証サービスが http://localhost:3001/dashboard で軽量なダッシュボードも提供します。

本番環境へのデプロイ方法についてはセルフホスティングガイドを、デプロイに関する完全なリファレンス（システム要件、環境変数、Docker/Kubernetes/Cloud Run の各オプション、セキュリティチェックリスト、モニタリング）については DEPLOYMENT.md を参照してください。Python の依存関係は requirements.txt に記載されています。

なぜオープン標準なのか？

Grantex はクローズドな SaaS 製品ではなく、オープンプロトコルとして構築されています。それが重要な理由は次のとおりです。

モデルに依存しません。 Grantex は特定のモデルプロバイダーに依存せず、SDK または保護対象サービスの境界で動作します。このプロジェクトのドキュメントでは、OpenAI、Anthropic、Google、Llama、Mistral のモデルとの使用方法を説明しています。

フレームワークにネイティブ対応しています。 LangChain、AutoGen、CrewAI、OpenAI Agents SDK、Google ADK、Strands Agents SDK、およびプレーンコード向けのファーストクラス統合を提供します。パッケージを 1 つインストールするだけで、既存のスタックに Grantex を導入できます。

オフラインで検証可能な署名。 サービスは公開済み JWKS を使用して、トークン署名をローカルで検証します。アプリケーションでは JWKS の取得と鍵のローテーションを計画する必要があります。発行者の停止中に利用できるかどうかは、検証側のキャッシュ動作によって異なります。

コンプライアンスを重視した制御。 EU AI Act、GDPR、および新たに登場している AI 規制では、自動化システムが何を行い、誰がそれを承認したかの記録がますます求められています。Grantex は、そうした取り組みを初日から支援できる技術的な制御を提供します。

スコープの命名規則

Grantex では、標準的なスコープ形式として resource:action[:constraint] を定義しています。

サービスプロバイダーは、自社の API 用のスコープ定義を実装します。エージェントは必要なスコープを宣言します。ユーザーに表示されるのは平易な説明であり、スコープ文字列そのものが表示されることはありません。

インテグレーション

この表は、2026-09-07 時点のソースとレジストリの状況を示すスナップショットです。主要な SDK の行は、2026-09-29 に確認されたリリーススナップショットに基づいています。 インテグレーションパッケージについては、「公開済みパッケージ」は公開されているパッケージの提供形態を示します。バージョンを選ぶ前に、レジストリのページと互換性に関する注記を確認してください。

コミュニティの x402 サービス

• JMT x402 Agent Tools は、検索、分析、市場データ、提出書類、企業情報、ニュースに対応した、Base メインネット上の有料ツールを提供します。検出エンドポイントに問い合わせると、最新のツールカタログと料金を確認できます。

フレームワークのクイック例

Express.js — トークンの検証とスコープベースの認可：

import express from 'express';
import { requireGrantToken, requireScopes } from '@grantex/express';

const JWKS_URI = 'https://api.grantex.dev/.well-known/jwks.json';

app.use('/api', requireGrantToken({ jwksUri: JWKS_URI }));
app.get('/api/calendar', requireScopes('calendar:read'), (req, res) => {
  res.json({ principalId: req.grant.principalId, scopes: req.grant.scopes });
});

FastAPI — スコープの適用を伴う依存性注入：

from fastapi import Depends, FastAPI
from grantex import VerifiedGrant
from grantex_fastapi import GrantexAuth, GrantexFastAPIError, grantex_exception_handler

app = FastAPI()
app.add_exception_handler(GrantexFastAPIError, grantex_exception_handler)
grantex = GrantexAuth(jwks_uri="https://api.grantex.dev/.well-known/jwks.json")

@app.get("/api/calendar")
async def calendar(grant: VerifiedGrant = Depends(grantex.scopes("calendar:read"))):
    return {"principalId": grant.principal_id}

LangChain — スコープを適用したツールと監査コールバック：

import { createGrantexTool } from '@grantex/langchain';

const tool = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  grantToken,
  requiredScope: 'calendar:read',
  func: async (input) => JSON.stringify(await getCalendarEvents(input)),
});
// Use with any LangChain agent — signature and scope checked locally using JWKS

Vercel AI SDK — 構築時にスコープを確認：

import { createGrantexTool } from '@grantex/vercel-ai';
import { z } from 'zod';

const tool = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  parameters: z.object({ date: z.string() }),
  grantToken,
  requiredScope: 'calendar:read',
  execute: async (args) => await getCalendarEvents(args.date),
});
// Use with generateText, streamText, etc.

AutoGen / OpenAI function calling：

import { createGrantexFunction, GrantexFunctionRegistry } from '@grantex/autogen';

const fn = createGrantexFunction({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  parameters: { type: 'object', properties: { date: { type: 'string' } }, required: ['date'] },
  grantToken,
  requiredScope: 'calendar:read',
  func: async (args) => await getCalendarEvents(args.date),
});

// Pass fn.definition to OpenAI, call fn.execute() when selected

CrewAI（Python）：

from grantex_crewai import GrantexTool

tool = GrantexTool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
)
# Use with any CrewAI agent

OpenAI Agents SDK（Python）：

from grantex_openai_agents import create_grantex_tool

tool = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
)
# Returns a FunctionTool — use with any OpenAI Agents SDK agent

Google ADK（Python）：

from grantex_adk import create_grantex_tool

read_calendar = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
)
# Returns a plain function — pass directly to google.adk.Agent(tools=[...])

Strands Agents SDK（Python）：

from grantex_strands import create_grantex_tool

read_calendar = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
)
# Returns a Strands-compatible tool — pass into your Strands agent tools list

CLI（90 種類以上のコマンドがあり、すべて AI エージェントやスクリプトでの利用向けに --json に対応）：

grantex config set --url https://api.grantex.dev --key YOUR_API_KEY
grantex me                                            # check identity
grantex agents register --name "Bot" --description "..." --scopes email:read
grantex agents update ag_... --redirect-uri https://client.example/grants/callback
grantex authorize --agent ag_... --principal [email protected] --scopes email:read
grantex tokens exchange --code <code> --agent-id ag_...
grantex tokens verify <jwt>
grantex tokens refresh --refresh-token <token> --agent-id ag_...
grantex grants delegate --grant-token <jwt> --agent-id ag_child... --scopes email:read
grantex budgets allocate --grant-id grnt_... --amount 100
grantex audit list --agent ag_...
grantex grants revoke grnt_...

# DPDP Act 2023 records (11 subcommands)
grantex dpdp consent create --grant-id grnt_... --principal-id [email protected]   --notice-id privacy-v1 --processing-expires-at 2027-01-01T00:00:00Z   --purposes '[{"code":"analytics","description":"Usage analytics"}]'
grantex dpdp consent get <recordId>
grantex dpdp consent list --principal [email protected]
grantex dpdp consent withdraw <recordId> --reason "No longer needed"
# Create a consent notice with the released --notice-version option:
grantex dpdp notices create --notice-id privacy-v1 --notice-version 1.0 --title "Privacy Notice" --content "We process your data for..." --purposes '[{"code":"analytics","description":"Usage analytics"}]'
grantex dpdp grievances file --principal-id [email protected] --type unauthorized-processing   --description "Data used beyond the consented purpose"
grantex dpdp grievances get <grievanceId>
grantex dpdp erasure [email protected]
grantex dpdp exports create --type dpdp-audit --date-from 2026-01-01 --date-to 2026-04-01
grantex dpdp exports get <exportId>
grantex dpdp principal-records [email protected]

# Machine-readable output for scripts and AI coding assistants
grantex --json agents list | jq '.[0].agentId'

インタラクティブなプレイグラウンド

ブラウザーで Grantex の認可フローを実際に試せます。サインアップは不要です。

grantex.dev/playground

プロトコルの全 7 ステップを体験できます。エージェントの登録、認可、トークンの交換、検証、更新、取り消し、取り消しの検証を行います。API キーを使ったサンドボックスモードで動作します。

例

アーキテクチャ

┌──────────────────────────────────────────────────────────────────────┐
│                         YOUR APPLICATION                             │
│                                                                      │
│   ┌──────────────┐    ┌──────────────┐    ┌───────────────────────┐ │
│   │  AI Agent    │    │  Grantex SDK │    │  End User Dashboard   │ │
│   │  (any model) │◄──►│  (2 lines)   │    │  (view / revoke)      │ │
│   └──────────────┘    └──────┬───────┘    └───────────────────────┘ │
└──────────────────────────────┼───────────────────────────────────────┘
                               │ HTTPS
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                         GRANTEX PROTOCOL                             │
│                                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐  ┌──────────┐  │
│  │  Identity   │  │     Auth     │  │   Consent   │  │  Audit   │  │
│  │  Service    │  │   Service    │  │     UI      │  │  Chain   │  │
│  │  (DID/JWKS) │  │ (token i/o)  │  │  (hosted)   │  │ (append) │  │
│  └─────────────┘  └──────────────┘  └─────────────┘  └──────────┘  │
└──────────────────────────────────────────────────────────────────────┘
                               │
                               ▼
                ┌──────────────────────────┐
                │  Any Service / API       │
                │  Verifies via JWKS       │
                │  No Grantex dep needed   │
                └──────────────────────────┘

プロダクトロードマップ

現在のプロダクトロードマップでは、2026.08 の本番環境における信頼性の基盤として、堅牢な MCP 認可、主要 SDK 間の同等性とリリースの安全性、失効を考慮した適用、プランの処理能力、本番環境向け Commerce の同意を優先しています。リポジトリの進捗は未リリースに記録されています。公開済みバージョン、デプロイ状況、制限事項については、リリース状況ガイド、互換性マトリックス、およびパッケージ固有のドキュメントが引き続き正式な情報源です。以下のラベルは過去のソースマイルストーンであり、リリースや本番環境への準備状況を示すものではありません。

コントリビューション

Grantex はコントリビューションを歓迎します。CONTRIBUTING.mdでは、Orchestrum Technologies LLP がコントリビューションを商用利用を含めてライセンスできるようにする、コントリビューションライセンスについて説明しています。

1. バグを報告する — 再現手順を添えてGitHub Issueを作成してください
2. 機能を提案する — ユースケースを添えてGitHub Discussionを作成してください
3. 新しいインテグレーションを構築する — お好みのフレームワークに Grantex のサポートを追加してください
4. ドキュメントを改善する — より良いサンプル、チュートリアル、翻訳を追加してください

PR を提出する前に、CONTRIBUTING.mdをお読みください。

標準とコンプライアンス

コンプライアンス対応表の全文：docs.grantex.dev/guides/compliance-matrix

ご利用者

Orchestrum との商用契約に基づいて Grantex をご利用ですか？ここへの掲載をご希望の場合は、[email protected] までご連絡ください。

FAQ

これは単なる認証ライブラリですか？
人間のアイデンティティシステムとGrantexは、異なるレイヤーの課題を解決します。人間の認証は人物が誰であるかを確立し、Grantexは、その人物または組織が特定のエージェントに委任した、スコープが限定された権限を担います。現在、権限を取り消すには、オンラインでの状態確認、または適用ポイントで同期された取り消しデータが必要です。

OAuth 2.0をそのまま使えばよいのではありませんか？
OAuth 2.0は、「ユーザーがアプリに自分のデータへのアクセス権を付与する」ように設計されました。エージェントには新たな要件があります。エージェントには作成者とは別に検証可能なアイデンティティが必要であり、複数エージェントのパイプライン全体で権限を連鎖でき、すべての自律的なアクションを追跡可能かつ監査可能にする必要があります。OAuth 2.0の概念を拡張しつつ、OAuth 2.0に欠けているエージェント固有のプリミティブを追加しています。

MCP（Model Context Protocol）についてはどうですか？
MCPはクライアントをツールやリソースに接続し、HTTPトランスポート向けのオプションのOAuthベース認可を定義します。Grantexは、ツールまたはサービスの境界でエージェント固有の委任権限を追加します。つまり、どのエージェントが、どの主体のために、どのアクションを実行できるかを定めます。この2つのレイヤーは相互補完的です。

この標準の所有者は誰ですか？
v1.0プロトコル仕様は、Orchestrum Personal Use License 1.0の下でこのリポジトリに公開されています。GrantexはOrchestrum Technologies LLPが所有し、Sanjeev Kumarが発明者および所有者として記載されています。Orchestrum Technologies LLPがリファレンス実装を保守しています。Revision -02は有効な個人IETF Internet-Draftとして公開されており、revision -03は審査中です。いずれの公開も、ワーキンググループによる採用、独立した認証、またはIETFの支持を意味するものではありません。

セルフホストできますか？
はい。SDKはApache-2.0で、用途を問わず無料で利用できます。認証サービスとポータルはOrchestrum Personal Use License 1.0の下で提供されています。個人は自身の個人的な用途に限りセルフホストできます。評価やパイロットを含め、組織による、または組織のためのセルフホストには、Orchestrum Technologies LLPから事前に書面で許可を得る必要があります（ライセンスを参照）。Docker Composeを使えば、1つのコマンドでデプロイできます。完全なガイドはDEPLOYMENT.md、またはセルフホストのドキュメントをご覧ください。

ライセンス

SDKとクライアントパッケージ（packages/）、およびサンプル（examples/）：Apache-2.0、 オープンソースで、用途を問わず無料で利用できます。認証サービス、ポータル、仕様書、 ドキュメント、ウェブサイト：Orchestrum Personal Use License 1.0の下で提供。 ライセンサーはOrchestrum Technologies LLPです。個人の個人的な用途に限り無料で、 組織が利用するにはOrchestrum Technologies LLPから事前に書面で許可を得る必要があります （COMMERCIAL-LICENSE.md、 [email protected]）。ディレクトリの適用範囲： LICENSING.md。商標：TRADEMARKS.md。

サードパーティのパッケージおよびTHIRD_PARTY_NOTICES.mdに 記載されているサードパーティのファイルには、それぞれのライセンスが適用されます。 再配布する前に、このファイルをご確認ください。

製品の所有者：GrantexはOrchestrum Technologies LLPが所有しています。発明者および所有者：Sanjeev Kumar。所有権に関するお問い合わせ：[email protected]または[email protected]。