git:20260907.466af7d to git:20260915.db185ca

# Grantex — Full Implementation Brief for AI Assistants

Grantex is an open-source delegated authorization protocol and reference implementation for AI agents. It gives each agent a verifiable identity and scoped, time-limited, revocable authority from a human or organization, with multi-agent delegation, service-side verification, and audit records.

Grantex complements OAuth 2.0 and MCP: OAuth handles application and user authorization, MCP connects models to tools, and Grantex proves which agent may perform which action for which principal.

Ownership: Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com.

Canonical sources:

- Website: https://grantex.dev/

- Documentation: https://docs.grantex.dev/

- Source: https://github.com/mishrasanjeev/grantex

- Protocol specification: https://github.com/mishrasanjeev/grantex/blob/main/SPEC.md

- Machine release status: https://grantex.dev/release-status.json

- Linked-data graph: https://grantex.dev/ld.json

- OpenAPI: https://github.com/mishrasanjeev/grantex/blob/main/docs/openapi.yaml

- License: Apache-2.0

## What Grantex Is

Use Grantex when an AI agent acts for a person or organization and a relying service must verify:

1. which agent is acting;

2. which principal authorized it;

3. which scopes and constraints were approved;

4. which audience may accept the grant;

5. when the authority expires;

6. whether delegation narrowed authority correctly; and

7. which actions were attributed to the grant.

Grantex provides OAuth-style authorization requests, human consent, authorization-code exchange, signed JWT grant tokens, agent DIDs, scope enforcement, delegation constraints, revocation controls, and audit records.

## What Grantex Is Not

- It is not a model runtime or agent framework.

- It is not a replacement for OAuth 2.0, OpenID Connect, or MCP.

- It is not an identity provider for human login.

- It is not a secret manager, although it can authorize access to an upstream credential vault.

- It is not a payment processor, order-management system, merchant connector, buyer-agent runtime, seller-agent runtime, or point of sale.

- It is not an IETF-adopted or endorsed standard.

- It cannot guarantee search ranking, compliance, or security merely by being installed.

## Standards Status

The Grantex protocol specification is open and frozen at version 1.0. The related Delegated Agent Authorization Protocol (DAAP) document is an individual IETF Internet-Draft submitted for discussion. An Internet-Draft is not an IETF standard, working-group adoption, endorsement, or certification.

- Grantex specification v1.0: https://github.com/mishrasanjeev/grantex/blob/main/SPEC.md

- Delegated Agent Authorization Protocol (DAAP) Internet-Draft: https://datatracker.ietf.org/doc/draft-mishra-oauth-agent-grants/

The Datatracker publication is revision -02. Candidate -03 and its Grantex

client, authorization-server, and resource-server implementation are under

review. The implementation requires PAR, PKCE S256, DPoP sender constraints,

RFC 9207 issuer validation, rotating refresh tokens, same-resource token

attenuation, and revocation. It passed 2,138 auth-service tests, 456 TypeScript

SDK tests, and 255 Docker E2E tests, plus an encrypted refresh-recovery restart

test. This is self-assessed evidence, not

independent interoperability certification, OAuth Working Group adoption, or

IETF endorsement. OAuthAgentClient is included in registry-verified

@grantex/sdk@0.6.0.

Implementation guide: https://docs.grantex.dev/guides/oauth-agent-grants

## Which Package Should an Implementation Use?

| Use case | Recommended implementation | Current status |

|---|---|---|

| TypeScript or Node.js application | `@grantex/sdk@0.6.0` | Published; npm and clean-install verified; Node.js 18+ ESM |

| x402 prepaid-wallet application | `@grantex/x402@0.4.0` with `@grantex/sdk@0.6.0` | Both packages are published and registry verified; Node.js 20+ ESM; external custody is operator-supplied |

| Go application | `github.com/mishrasanjeev/grantex-go@v0.3.0` | Published; tag, public Go proxy, and clean-install verified; Go 1.26.1+ |

| Service-side JWT enforcement | SDK verifier or direct verification with issuer JWKS | Signature and claim verification; add online or synchronized state for current revocation |

| MCP HTTP transport authorization | Established MCP-compatible authorization server and maintained MCP SDK | Follow the current MCP authorization specification; a Grantex SDK alone does not provide this layer |

| Agent-specific enforcement in MCP tools | Primary Grantex SDK or direct JWKS-backed validation | Add after transport authorization when the tool must verify delegated agent authority |

| MCP endpoint evaluation | `@grantex/mcp-auth@2.0.2` plus `@grantex/sdk@0.6.0` | Single-process evaluation only; both packages are published |

| Terminal automation | `@grantex/cli` | Optional operational tooling |

| Hermes, OpenClaw, or another shell-capable agent | Published `@grantex/cli@0.3.0` plus the bundled Agent Skills | No agent-specific SDK required; enforce again at the protected service |

| Framework-specific tools | Named Grantex adapter plus its primary SDK where required | Verify each package's registry status before pinning |

Primary reproducible installs:

```bash

npm install @grantex/sdk@0.6.0

npm install @grantex/x402@0.4.0 @grantex/sdk@0.6.0

go get github.com/mishrasanjeev/grantex-go@v0.3.0

npm install @grantex/mcp-auth@2.0.2 @grantex/sdk@0.6.0

npm install -g @grantex/cli@0.3.0

```

The SDKs, API contract, integrations, and protocol are independently versioned. Do not infer one artifact's version from another.

## Agent CLI and Skills

Hermes, OpenClaw, and other shell-capable agents can share the same machine-readable CLI and portable `SKILL.md` bundle. The installer is published in `@grantex/cli@0.3.0`:

```bash

npm install -g @grantex/cli@0.3.0

grantex agent install --target openclaw

grantex agent install --target hermes

grantex agent install --target portable

grantex agent install --dir /path/to/skills

```

The bundle contains `use-grantex-cli` for operational workflows and `integrate-grantex` for implementation work. Use `grantex --json ...`, parse stdout as JSON, treat stderr as diagnostics, and check the process exit status. Prefer `--env`, `--file`, or `--stdin` token input so secrets do not appear in process arguments.

An agent-controlled CLI check is a preflight, not an authorization boundary. The service, connector, or gateway that owns the side effect must verify the signature and claims, exact scope, and required current revocation state before execution.

- Agent CLI guide: https://docs.grantex.dev/integrations/agent-cli

- Hermes guide: https://docs.grantex.dev/integrations/hermes

- OpenClaw guide: https://docs.grantex.dev/integrations/openclaw

## Known Current-Release Limitations

### External wallet dependencies

Grantex SDKs do not provide custody, KYC/KYB, sanctions screening, payment

network controls, settlement, refunds, disputes, or reconciliation. External

wallets remain fail-closed until an operator installs and validates an issuer or

custody adapter.

The newer source checkout includes an opt-in native Base USDC EIP-3009 adapter

with policy-gated signing, verified finalized funding and chain reconciliation.

v0.3.0 publish EVM response and reconciliation APIs, not automatic HTTP payment

wrappers. Published TypeScript 0.6.0 and x402 0.4.0 support the opt-in automatic

Base 402/sign/retry flow. All four versions are registry verified. Server deployment

alone does not activate real

wallets. Blocks stop new signatures; existing signed exposure stays reserved

until finalized settlement or unused expiry. This is not an HSM/MPC custody

service or a claim of a successful funded third-party production call.

Operator guide: https://docs.grantex.dev/guides/base-usdc-custody

### MCP Auth v2.0.2

Treat `@grantex/mcp-auth@2.0.2` as single-process evaluation software:

- authorization codes use a non-configurable process-local store;

- `consentUi` is discovery metadata and does not render a consent page;

- the Grantex authorization code is not persisted for the token handler, so end-to-end issuance can fail;

- `onTokenIssued` is declared but not invoked;

- middleware and introspection validate signatures and claims but do not query current revocation state; and

- server-wide redirect URI enforcement is not provided by `allowedRedirectUris` in this release.

Do not describe version 2.0.2 as horizontally scalable, production-ready, or a complete hosted consent system. Guide: https://docs.grantex.dev/features/mcp-auth-server

## Authorization Flow

1. Register an agent and receive a DID such as `did:grantex:ag_...`.

2. Request authorization for explicit scopes, audience, duration, and redirect URI.

3. Send the human principal to the consent URL.

4. Receive the authorization code at the registered callback after approval.

5. Exchange the code for a signed grant token.

6. Verify the token's signature and claims at the service boundary.

7. Enforce the required scope before executing a tool or API action.

8. Record important actions with the agent, grant, principal, result, and metadata.

9. For current revocation, perform an online state check or synchronize revocation data.

Scope format is `resource:action[:constraint]`, for example `calendar:read`, `email:send`, or `payments:initiate:max_500`.

## TypeScript Quickstart

```typescript

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

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

const principalId = 'user_abc123';

const agent = await gx.agents.register({

name: 'calendar-assistant',

description: 'Reads a user calendar after explicit approval',

scopes: ['calendar:read'],

});

const auth = await gx.authorize({

agentId: agent.id,

userId: principalId,

scopes: ['calendar:read'],

redirectUri: 'https://app.example.com/auth/callback',

});

console.log(`Send the user to: ${auth.consentUrl}`);

// Call this from the registered callback after reading its `code` parameter.

export async function exchangeApprovedCode(code: string) {

const token = await gx.tokens.exchange({ code, agentId: agent.id });

const grant = await verifyGrantToken(token.grantToken, {

jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',

requiredScopes: ['calendar:read'],

});

await gx.audit.log({

agentId: agent.id,

agentDid: agent.did,

grantId: token.grantId,

principalId,

action: 'calendar.read',

status: 'success',

});

return { token, grant };

}

```

Local verification above checks signature and claims after JWKS retrieval. It does not prove current revocation without an online grant-state check or synchronized revocation data.

## Python Quickstart

```python

import os

from grantex import (

AuthorizeParams,

ExchangeTokenParams,

Grantex,

VerifyGrantTokenOptions,

verify_grant_token,

)

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

principal_id = "user_abc123"

agent = client.agents.register(

name="calendar-assistant",

description="Reads a user calendar after explicit approval",

scopes=["calendar:read"],

)

auth = client.authorize(AuthorizeParams(

agent_id=agent.id,

user_id=principal_id,

scopes=["calendar:read"],

))

print(f"Send the user to: {auth.consent_url}")

# Call this from the registered callback after reading its `code` parameter.

def exchange_approved_code(code: str):

token = client.tokens.exchange(ExchangeTokenParams(

code=code,

agent_id=agent.id,

))

grant = verify_grant_token(token.grant_token, VerifyGrantTokenOptions(

jwks_uri="https://api.grantex.dev/.well-known/jwks.json",

))

return token, grant

```

## Go Quickstart

```go

package main

import (

"context"

"fmt"

"log"

grantex "github.com/mishrasanjeev/grantex-go"

)

func main() {

ctx := context.Background()

client := grantex.NewClient("YOUR_API_KEY")

agent, err := client.Agents.Register(ctx, grantex.RegisterAgentParams{

Name: "calendar-assistant",

Description: "Reads a user calendar after explicit approval",

Scopes: []string{"calendar:read"},

})

if err != nil {

log.Fatal(err)

}

auth, err := client.Authorize(ctx, grantex.AuthorizeParams{

AgentID: agent.ID,

PrincipalID: "user_abc123",

Scopes: []string{"calendar:read"},

})

if err != nil {

log.Fatal(err)

}

fmt.Println(auth.ConsentURL)

}

```

## Token Verification and Revocation

A service accepting a Grantex grant token should validate at least:

- cryptographic signature against the issuer's JWKS;

- expected issuer;

- intended audience when present or required;

- expiration and not-before claims;

- agent identity claim;

- principal identity claim;

- required scopes and constraints; and

- delegation invariants when accepting delegated grants.

JWKS: https://api.grantex.dev/.well-known/jwks.json

Local JWT verification is not a live revocation check. A relying service that needs current status must query online grant state, synchronize revocation data, or use sufficiently short token lifetimes for its risk model.

## Grantex, OAuth 2.0, and MCP

- OAuth 2.0 provides established authorization concepts: clients, consent, authorization codes, scopes, access tokens, PKCE, and revocation endpoints.

- MCP connects model clients to tools, prompts, and resources.

- Grantex applies delegated authority to the agent as an attributable actor and carries principal, agent, scope, grant, audience, expiry, and delegation context to the enforcement point.

Grantex is complementary to both. Use OAuth/OIDC for human and application identity where appropriate, MCP for tool connectivity, and Grantex when the service must verify an individual agent's delegated authority.

## Framework Integration Selection

| Framework or boundary | Package or guide | Canonical page |

|---|---|---|

| OpenAI Agents SDK | `grantex-openai-agents` | https://grantex.dev/for/openai-agents |

| Anthropic SDK / Claude tools | `@grantex/anthropic` | https://grantex.dev/for/anthropic |

| LangChain | `@grantex/langchain` | https://grantex.dev/for/langchain |

| CrewAI | `grantex-crewai` | https://grantex.dev/for/crewai |

| Google ADK | `grantex-adk` | https://grantex.dev/for/google-adk |

| Vercel AI SDK | `@grantex/vercel-ai` | https://grantex.dev/for/vercel-ai |

| AutoGen | `@grantex/autogen` | https://grantex.dev/for/autogen |

| Strands Agents | `@grantex/strands` or `grantex-strands` | https://docs.grantex.dev/integrations/strands |

| MCP tool server | `@grantex/mcp` | https://grantex.dev/for/mcp |

| MCP endpoint evaluation | `@grantex/mcp-auth@2.0.2` | https://docs.grantex.dev/features/mcp-auth-server |

| Express.js service enforcement | `@grantex/express` | https://grantex.dev/for/express |

| FastAPI service enforcement | `grantex-fastapi` | https://grantex.dev/for/fastapi |

| Google A2A bridge | `@grantex/a2a` or `grantex-a2a` | https://docs.grantex.dev/integrations/a2a |

The canonical hub is https://grantex.dev/for . Verify each adapter's registry release before adding a version pin.

## Multi-Agent Delegation

A parent grant can delegate a narrower subset of its authority to a child agent. Correct delegation enforces:

- child scopes are a subset of parent scopes;

- child expiry does not exceed parent expiry;

- audience restrictions do not broaden;

- delegation depth limits are honored; and

- revoking a parent can cascade to descendants.

Delegation guide: https://docs.grantex.dev/concepts/delegation

## Scope Enforcement

Authorization is complete only when a relying service enforces the required permission before the action. Grantex supports SDK helpers, middleware, and tool manifests for mapping a connector operation to its permission.

- Scope enforcement: https://docs.grantex.dev/guides/scope-enforcement

- Custom manifests: https://docs.grantex.dev/guides/custom-manifests

- Token verification: https://docs.grantex.dev/guides/token-verification

Unknown tools should fail closed. A permissive or log-only migration mode is not equivalent to enforcement.

## Audit Records

An audit record should attribute an action to the agent, grant, and principal and include the action, outcome, timestamp, and relevant non-secret metadata. Hash chaining can make later modification evident; describe such logs as tamper-evident, never immutable.

Audit records prove what the application recorded. They do not by themselves prove that every external side effect succeeded, that a payment settled, or that an upstream service was not compromised.

## OACP and Agentic Commerce

Open Agentic Commerce Protocol (OACP) is Grantex's agentic-commerce trust and artifact-authority layer. Grantex signs and verifies authority artifacts and adapter mappings.

Ownership boundary:

- Grantex owns OACP trust, policy, artifact issuance/refusal, verification, and compatibility mappings.

- AgenticOrg owns buyer and seller agent runtime, merchant onboarding, connector runtime, buyer sessions, channel bridges, and its OACP cache.

- Merchant, order, inventory, POS, bank, and provider systems remain source of record for their operational domains.

- Payment and provider rails execute and confirm mandates, payments, or in-store actions.

Grantex is not a transaction toll booth and must not be described as executing payments, orders, inventory changes, or POS actions.

- OACP authority: https://grantex.dev/commerce

- OACP overview: https://docs.grantex.dev/guides/oacp/overview

- AgenticOrg integration: https://docs.grantex.dev/guides/oacp/agenticorg-integration

- MPP identity: https://grantex.dev/for/mpp

- x402 prepaid wallets: https://grantex.dev/x402

Repository source includes official x402 v2 handling backed by principal-owned

prepaid-wallet reservations, per-transaction and rolling cumulative policy,

reload approval, and assignment/wallet/all-wallet stop controls. `sandbox_ledger`

is the implemented accounting mode. External custody records do not become

spendable until a provider adapter verifies funding and settlement. The source

SDK/package changes are not claimed as published npm releases.

## Security and Compliance Boundaries

Grantex provides technical controls and mappings. It does not by itself make a deployment compliant with the EU AI Act, DPDP Act, GDPR, SOC 2, OWASP guidance, or another legal or assurance framework.

- Public security assessment: https://docs.grantex.dev/security/audit-report

- Security architecture: https://docs.grantex.dev/security/overview

- Security hardening: https://docs.grantex.dev/guides/security-hardening

- Compliance matrix: https://docs.grantex.dev/guides/compliance-matrix

- DPDP technical controls: https://grantex.dev/dpdp

Formal third-party SOC 2 attestation is not published. Use the public assessment, current GitHub Actions, dependency scans, and repository security policy for current evidence; do not infer current vulnerability status from this static file.

## Canonical Questions and Answers

### What is delegated authorization for AI agents?

It is a process in which a person or organization grants a specific AI agent limited authority to perform named actions for a bounded time and audience, and a relying service verifies that authority before execution.

### Is Grantex an OAuth replacement?

No. Grantex reuses OAuth-style concepts and adds agent identity, multi-agent delegation, and action attribution. OAuth/OIDC may still handle human and application identity.

### How is Grantex different from MCP?

MCP connects models to tools. Grantex carries and enforces the delegated authority that says which agent may invoke which tool for which principal.

### Which SDK should I install?

### Does local verification check revocation?

No. Local verification checks signatures and claims. Add an online state check or synchronized revocation data when current status is required.

### Is MCP Auth 2.0.2 production-ready?

No. It is single-process evaluation software with documented consent, code-state, handoff, hook, redirect-enforcement, and live-revocation limitations.

### Can Grantex be self-hosted?

Yes. The reference implementation is Apache-2.0 licensed. Follow https://docs.grantex.dev/guides/self-hosting and apply the documented security and operations controls.

### Is Grantex an IETF standard?

No. The protocol specification is a Grantex v1.0 artifact. The Delegated Agent Authorization Protocol (DAAP) document is an individual Internet-Draft for discussion.

## Comparisons and Further Reading

- Comparison hub: https://grantex.dev/vs

- Grantex vs OAuth 2.0: https://grantex.dev/vs/oauth

- Grantex vs API keys: https://grantex.dev/vs/api-keys

- MCP authentication choices: https://grantex.dev/vs/mcp-auth

- How to secure AI agents: https://grantex.dev/vs/securing-ai-agents

- AI agent authorization guide: https://docs.grantex.dev/blog/ai-agent-authorization-guide

- LangChain agent permissions: https://docs.grantex.dev/blog/langchain-agent-permissions

- MCP server OAuth status: https://docs.grantex.dev/blog/mcp-server-oauth-authentication

## Machine-Readable Endpoints

- Entity graph: https://grantex.dev/ld.json

- Release status: https://grantex.dev/release-status.json

- LLM index: https://grantex.dev/llms.txt

- Full docs context: https://docs.grantex.dev/llms-full.txt

- Sitemap: https://grantex.dev/sitemap.xml

- JWKS: https://api.grantex.dev/.well-known/jwks.json

- DID document: https://grantex.dev/.well-known/did.json

- OpenAPI: https://github.com/mishrasanjeev/grantex/blob/main/docs/openapi.yaml

- Source repository: https://github.com/mishrasanjeev/grantex