Grantex

Grantex

AI Agent 授权与委托访问，配备开源 SDK

OAuth 2.0 之于人类，正如 Grantex 之于 Agent。

文档 | 快速入门 | 发布 JSON | LLM 索引 | 规范 | IETF 草案

所有权： Grantex 归 Orchestrum Technologies LLP 所有。发明人及所有者：Sanjeev Kumar。联系方式：[email protected] 或 [email protected]。

网站运营方：营销咨询的递交与受理。

如需开展范围明确的技术试点，请先了解安全控制、 令牌验证以及 OACP 权限边界。 AgenticOrg 运行买方／卖方 Agent 和工作流；Grantex 管理委托权限；商户系统和支付服务提供商保留运营权限。 如需讨论银行、金融科技或商户集成事宜，请联系 [email protected]，但请勿分享凭据 或客户隐私记录。

Grantex 使用两种许可证。LICENSING.md 列出了各目录使用的许可证。

• **平台，免费：**个人出于自身目的使用、复制或修改（用于学习、个人研究、实验和业余项目），且不代表任何组织行事、不为任何组织行事或谋取任何组织的利益。
• **平台，需事先获得 Orchestrum Technologies LLP 的书面许可：**任何组织直接或间接进行的使用，无论组织是公司、事务所、个体经营者、慈善机构、学校、大学、研究机构还是政府部门，也无论使用是否付费。包括评估、测试、试点、内部使用、托管或 SaaS、转售、分发，以及将平台嵌入其他产品。通过托管服务（grantex.dev API）进行的商业使用也需要签署协议，即使是通过开源 SDK 使用。请参阅 COMMERCIAL-LICENSE.md，并联系 [email protected]。
• **现有用户：**2026 年 10 月 21 日之前发布的版本仍按发布时所附的条款提供。自该日起发布的平台版本和更新不适用这些条款，因此组织需要获得书面许可才能使用。
• 名称：“Grantex”和“AgenticOrg”是 Orchestrum Technologies LLP 的商标。未经 Orchestrum 事先书面批准，不得将这些名称、徽标或品牌用于商业用途，包括与 Apache 许可的 SDK 和早期版本一同使用。请参阅 TRADEMARKS.md。

什么是 Grantex？

Grantex 是一套面向 AI Agent 的委托授权协议和参考实现，提供开源 SDK 和源码可用的服务端。它为每个 Agent 提供可验证的身份，以及由个人或组织授予的、范围受限、具有时效且可撤销的权限，并支持多 Agent 委托、服务端验证和审计记录。

Grantex 与 OAuth 2.0 和 MCP 相辅相成：OAuth 负责应用和用户授权，MCP 连接模型与工具，而 Grantex 用于证明哪个 Agent 可以代表哪个主体执行哪些操作。当 AI Agent 代表个人或组织行事，而依赖该 Agent 的服务必须准确验证其可执行操作时，请使用 Grantex。

对于 AgenticOrg 的企业入驻场景，Grantex 授予委托的工具权限，而 AgenticOrg 负责租户隔离、案例状态、本地案例用途允许列表、人工审核以及提供商调用边界。最近一次经过验证的 AgenticOrg 集成并未强制执行令牌级别的案例用途或每个案例的限额。已发布的 Python grantex==0.7.2 包含用途和限额 API，但尚未验证该集成是否使用了这些 API。请参阅受管控案例集成边界和发布状态。本仓库和 MCP 工具均不会授予 Agent 批准案例的人工权限。

Agent 预付钱包和 x402 v2

仓库源码包含由委托主体控制、供 AI Agent 使用的预付钱包。 委托主体可以分配一个或多个钱包，并实施分配、钱包、 Agent、共享预算组、委托主体和开发者级控制，限制 收款方、资源来源、操作、商户、用途、项目和成本中心，要求 获得确切的人为审批，管理充值频率，并停用一个 分配、一个钱包或 Agent 可用的所有钱包。授权会在 PostgreSQL 中以原子方式 预留金额，并绑定到 Agent 的 DPoP OAuth 身份和经策略评估的语义上下文。

@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；两者都未添加 自动 HTTP 支付封装。已发布的 TypeScript 0.8.2 和 x402 0.4.1 包含可选启用的 Base 自动 402/签名/重试流程。四个版本均已通过注册表验证。请参阅 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 负责委托 Agent 身份、语义支出策略、跨钱包预算、确切审批、原子预留、停用控制和审计。AgenticOrg 部署或其他 Agent 运行时负责编排和与人类交互。钱包发行方或托管方仍负责 KYC/KYB、AML 和制裁管控、托管、网络授权、MCC/地理位置/卡片控制、结算、外汇、退款、争议、欺诈和对账。商户仍负责由服务器可信的数据确定价格/收款方、订单幂等性、结算门控，以及交付已支付的结果。

请参阅Agent 钱包治理，了解完整的责任矩阵、策略组合、确切审批协议和如实列出的剩余差距。

托管客户端已在通过注册表验证的 @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 也会导致 Agent 无法访问钱包）；
• 在使用 external 钱包之前，接入特定提供商的托管、资金注入、结算、Webhook 去重和恢复适配器；如果没有适配器，Grantex 会有意返回 503 CUSTODY_ADAPTER_UNAVAILABLE；
• 当必须通过电子邮件、SMS、Slack、WhatsApp 或其他外部渠道通知主体时，提供用于重新加载事件的 SSE/WebSocket 通知桥接；不承诺内置钱包邮件投递功能；
• 商户端持久化结果缓存，以 HTTP Idempotency-Key 为键，用于结算后的副作用；
• 独立的安全、提供商、对账、事件响应及适用的法律/监管审查。

服务端部署与各 SDK 版本是相互独立的。注册表使用者在安装前应核实确切版本，而不要根据仓库清单推断其是否可用。 生产就绪指南包含完整的托管检查清单，以及仅供维护者使用的 PowerShell 发布操作手册。

供应链与许可证控制

安全工作流会审计所有受跟踪的 npm 锁文件、所有受跟踪的 Python 项目和 requirements 清单，以及全部三个 Go 模块。它会检查 Dependabot 是否覆盖仓库清单，将外部 GitHub Actions 和容器镜像固定到不可变摘要，并在 CI 中拒绝未经审查的 npm 许可证标识符。发布前，请在本地运行 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 配置文件

托管式身份验证服务和 TypeScript 仓库客户端实现了候选版本 draft-mishra-oauth-agent-grants-03 中的三个角色。经过测试的配置文件要求使用 PAR、PKCE S256、DPoP 发送方约束、RFC 9207 响应颁发者验证、5 分钟访问令牌、带家族重放撤销机制的轮换刷新令牌、在刷新响应丢失时提供 300 秒的精确请求恢复、带过期清理机制的 AES-256-GCM 加密恢复状态、同一资源的 RFC 8693 权限收窄，以及 RFC 7009 撤销。

验证已完成，包括 2,138 个身份验证服务测试、456 个 TypeScript SDK 测试，以及 23 个按顺序执行的 Docker E2E 文件中的 255 个测试。这些是针对经过测试的 Grantex 配置的自评证据，并非独立的互操作性认证、OAuth 工作组采纳或 IETF 背书。更新后的 OAuthAgentClient 已以通过注册表验证的 @grantex/[email protected] 发布。

修订版 -02 仍是 Datatracker 上当前发布的版本。候选版本 -03 不得在 2026-09-09 之前上传，且须在预定的最终审查后获得新的明确批准。

开放式 Agent 商务协议（OACP）权威层

开放式 Agent 商务协议（OACP）是 Grantex 的 Agent 商务信任与制品权威层。Grantex 负责管理 OACP 策略、签署制品和授权的签发或拒绝、验证以及兼容性适配器。AgenticOrg 负责买方和卖方 AI Agent 运行时、商户自助入驻、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]

Agent Trust Registry：经认可的签发方与 Agent 护照

该注册表让依赖方（例如商户、支付服务提供商或 API）能够在 AI Agent 执行操作前对其进行检查。它回答三个问题：该 Agent 是什么软件、持有什么密钥，以及哪个经认可的签发方为其背书。返回的是计算得出的信任级别，而不是 Agent 自行声明的内容。授权仍规定 Agent 可以执行哪些操作；护照则说明 Agent 的身份。请参阅护照与授权。

现有路径上的新行为默认关闭。请按部署启用：

• REGISTRY_PUBLIC_ENDPOINTS_ENABLED 提供无需身份验证的读取接口：签发方列表、状态列表、无需 API 密钥的查询，以及清单。
• PASSPORT_BOUND_GRANTS_ENABLED 启用绑定护照的授权。
• AGENT_KEY_HISTORY_MIRROR_ENABLED 使 POST 和 PATCH /v1/agents 将 Agent 的密钥写入密钥历史记录，并拒绝已泄露或属于其他 Agent 的密钥。
• REGISTRY_ATTESTATION_EDDSA_ENABLED 除 ES256 外，还接受 EdDSA 证明。

自托管列出了所有变量。面向各类受众的指南：

• 成为经认可的签发方
• 注册 Agent，面向提供方
• 验证 Agent，面向依赖方

规范包括注册表联合、证明、Agent 密钥、Agent Passport 1.0、护照绑定和验证。此 Agent Passport 是由经认可的签发方签发的 SD-JWT VC，与下文#mpp-agent-identity所述的 MPP AgentPassportCredential 相互独立。

演示：开发者选择加入的证明

make demo-attest 会针对仓库的模拟认证发行方端到端运行注册流程，无需任何外部参与方：注册 Agent、证明其密钥、通过发行方适配器接口请求证明、在公开查询中看到等级为 attested，在发行方处撤销，并看到等级下降。make demo-verify 会继续演示与护照绑定的授权、依赖方的 verify() 验证通过、发行方撤销后 verify() 拒绝，以及验证器的对抗性测试样例全部被拒绝。每一步都标注为 live（注册表）、fixture（模拟发行方）或 verifier。请参阅运行模拟发行方和验证 Agent。

当前版本

Grantex 的各组件分别进行版本管理。协议规范仍为 v1.0 Final；SDK、MCP 软件包和路线图里程碑的版本属于独立的发布线，并不代表整个 monorepo 的统一版本。

以下公开版本已于 2026-10-04 核实。在相应的软件包注册表确认发布之前，仓库中的版本均为候选版本。

当前版本为：TypeScript 0.8.2、Python 0.7.2、Go v0.4.3、CLI 0.4.2、gateway 0.3.0 和 MCP Auth 4.1.0。升级前请参阅完整的迁移指南：Node.js 要求、受众绑定、限额调用金额和默认在线撤销均为破坏性变更。

TypeScript 0.8.2 和 Python 0.7.2 默认包含服务端 enforce() 受众绑定、拒绝金额不受信任的限额调用，以及在线撤销。进行受众绑定授权前，请先注册 Agent 的资源服务器，在服务边界配置预期受众，并为每次限额调用提供经过验证的金额。仅进行离线验证无法证明当前撤销状态；集成必须明确接入当前状态的强制检查。变更后的 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 Authorization Server（@grantex/mcp-auth）：提供 OAuth 2.1 + PKCE 端点，并支持持久化存储适配器、呈现式同意页面、经身份验证的人类主体解析、资源绑定和当前授权验证；版本 4 要求配置主机身份验证
• MCP Tool Server（@grantex/mcp）：面向 Agent 的 Grantex 工具，供 MCP 客户端使用
• @grantex/dpdp：DPDP Act 2023 和 EU AI Act 控制映射
• 信任注册表：公共 DID 验证注册表 — grantex.dev/registry
• grantex verify：令牌检查 CLI — 无需账户
• Agent CLI 技能：为 Hermes、OpenClaw 和可移植的 Agent Skills 客户端提供一键式 SKILL.md 安装
• 异常检测：四项已实现的、由 SQL 驱动的检查、生命周期 API，以及已存储的规则／渠道配置；通知发送需要主机工作进程

SDK 快速入门

执行权限与人类身份

仅验证签名无法确立当前权限，也无法证明执行任务的 Agent 属于经身份验证的人类。已发布的 TypeScript SDK 0.8.1 新增了可选的逐次调用颁发方检查，以及受信任的主体／Agent 绑定。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 和任意 Agent CLI

支持 Shell 的 Agent 使用相同的 JSON 优先 CLI；无需针对特定 Agent 的 SDK：

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 Agent 正在代表真实用户预订旅行、发送电子邮件、部署代码和花钱。但：

• 无法限定权限 — Agent 获得的访问权限与密钥所有者相同
• 无需征得同意 — 用户从未批准 Agent 可以执行的操作
• 没有 Agent 独立身份 — 你知道密钥被使用了，却不知道是哪个 Agent 使用的，也不知道原因
• 无法精细撤销 — 一个 Agent 行为不当，就得轮换密钥，全部停用
• 无法控制委派 — Agent A 调用 Agent B？只能复制粘贴凭据
• 没有支出限制 — 持有云 API 密钥的 Agent 可以无限创建资源

OAuth 和 IAM 提供了必要的基础，但许多 Agent 部署仍依赖共享凭据，无法识别具体 Agent，也无法明确编码其被委派的权限。

工作原理

快速入门

1. 注册 Agent

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

刷新令牌只能使用一次，每次刷新成功后都会轮换。如果服务器已提交更改，但 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），并扩展了 Agent 专属声明。任何服务都可以使用发行方公布的 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"
}

委派声明（存在于子 Agent 令牌中）：

多 Agent 委派

Grantex 支持多 Agent 工作流，根 Agent 可派生权限范围更窄的子 Agent。子 Agent 令牌包含完整的委派链，任何服务都可以检查该链。

// 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",
)

协议强制执行的约束：

• 子 Agent 的权限范围必须严格小于父 Agent 的权限范围 — 权限范围升级会被拒绝，并返回 400
• 子 Agent 令牌的有效期为 min(parent expiry, requested expiry) — 子 Agent 的有效期绝不会超过父 Agent
• 撤销根授权会以原子方式级联撤销所有后代授权

高级功能

// 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

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

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

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() 提供 TypeScript Agent 框架辅助工具，包括 Strands Agents SDK。create_grantex_tool() 提供适用于 Python OpenAI Agents SDK、Google ADK 和 Strands Agents SDK 工具的辅助功能。enforceMiddleware() 可为 Express/Fastify 路由添加一行代码即可启用执行。FastAPI 使用 GrantexEnforcer 依赖项。

完整文档请参阅作用域执行指南。

本地开发

使用 Node.js 24 LTS 安装、构建和测试仓库。升级后的 Vitest 5 工具链需要 Node.js 22.12 或更高版本；这是贡献者要求，与已发布 SDK 的运行时要求不同。 使用仓库中已提交的锁文件运行 npm ci，并参阅 CONTRIBUTING.md。

使用一条命令启动完整技术栈：

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

系统会自动预置两个 API 密钥：

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 密钥，即可在浏览器中管理 Agent、授权、策略、异常、合规性导出和账单。

实时授权与异常情况的账户设置：“账单”页面会显示你账户的实际套餐。源码限制为：Free 套餐最多 1,000 个活跃授权，Pro 套餐最多 50,000 个，Enterprise 套餐不限；限制按开发者账户统计，而非按 Agent 统计。使用经过身份验证的 GET /v1/billing/subscription 查询已部署账户；仅凭 Agent ID 无法得知其套餐。如果设置了 IRREGULARITY_RESPONSE_POLICY_ENABLED=true，“异常情况”页面可对 POST /v1/anomalies/detect 返回的发现启用账户级 alert_only 响应策略。未启用此服务端标志时，检测器仍会在发现高危或严重问题时，按原有方式撤销该 Agent 的所有活跃授权。仅告警会保留告警，不会绕过手动撤销或独立的安全防护机制。请参阅设置指南。服务端是否可用取决于部署情况和发布标志。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 以及纯代码。安装一个包，即可在现有技术栈中使用 Grantex。

可离线验证的签名。 服务使用公开发布的 JWKS 在本地验证令牌签名。应用应规划好 JWKS 获取和密钥轮换；签发方服务中断期间能否继续可用，取决于验证器的缓存行为。

面向合规的控制。 欧盟《人工智能法案》、GDPR 以及新兴的 AI 法规越来越要求记录自动化系统执行了哪些操作，以及由谁授权。Grantex 从一开始就提供可支持这些计划的技术控制。

范围命名约定

Grantex 定义了标准范围格式：resource:action[:constraint]

服务提供商为其 API 实现范围定义。Agent 声明所需的范围。用户看到的是通俗易懂的说明，而不是原始范围字符串。

集成

此表是截至 2026-09-07 的来源与注册状态快照；主要 SDK 条目依据经 2026-09-29 核实的发布快照。对于集成包，“已发布的软件包”表示公开的软件包入口；选择版本前，请查看其注册表页面和兼容性说明。

社区 x402 服务

• JMT x402 Agent 工具 提供运行于 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 函数调用：

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 多条命令，全部支持 --json，供 AI Agent / 脚本使用）：

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'

交互式 Playground

在浏览器中实时体验完整的 Grantex 授权流程 — 无需注册：

grantex.dev/playground

逐步体验协议的全部 7 个步骤：注册 Agent、授权、交换令牌、验证、刷新、撤销，以及验证撤销结果。使用沙盒模式和你的 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]，以便列入此处。

常见问题

这只是另一个身份验证库吗？
人类身份系统和 Grantex 解决的是不同层面的问题。人类身份验证用于确认个人身份；Grantex 则承载该个人或组织委托给特定 Agent 的限定权限。目前，撤销权限需要在执行点进行在线状态检查，或同步撤销数据。

为什么不直接使用 OAuth 2.0？
OAuth 2.0 的设计初衷是“用户授权应用访问其数据”。Agent 带来了新的需求：Agent 需要有可验证的身份，且该身份应与其创建者相互独立；授权需要能在多 Agent 流水线中逐级传递；每个自主操作都必须可追溯、可审计。我们在扩展 OAuth 2.0 概念的同时，加入了它所缺少的 Agent 专用基础机制。

MCP（Model Context Protocol）呢？
MCP 将客户端连接到工具和资源，并为 HTTP 传输定义可选的 OAuth 授权。Grantex 则在工具或服务边界添加 Agent 专用的委托权限：哪个 Agent 可以代表哪个主体执行什么操作。这两个层面相辅相成。

谁拥有这项标准？
v1.0 协议规范依据 Orchestrum Personal Use License 1.0 发布在此代码库中。Grantex 归 Orchestrum Technologies LLP 所有，Sanjeev Kumar 列为发明人和所有者。Orchestrum Technologies LLP 维护参考实现。修订版 -02 作为有效的个人 IETF Internet-Draft 发布，修订版 -03 正在审查中；无论是发布草案还是在代码库中实现，都不代表工作组采纳、独立认证或 IETF 背书。

我可以自行托管吗？
可以。SDK 采用 Apache-2.0 许可，可免费用于任何用途。身份验证服务和门户采用 Orchestrum Personal Use License 1.0 许可：个人可以自行托管以供本人使用；任何组织自行托管或为其托管（包括评估和试点）均需事先获得 Orchestrum Technologies LLP 的书面许可（参见许可）。只需一条命令即可通过 Docker Compose 部署。完整指南请参见 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]。