DEV Community: Sanjeev Kumar

How We Made Grantex Enterprise-Grade: 3,332 Tests, Zero Failures

Sanjeev Kumar — Sun, 05 Apr 2026 12:34:49 +0000

TL;DR: We ran a comprehensive security, resilience, and API quality audit on Grantex — the open authorization protocol for AI agents. We found and fixed 20+ issues across security (timing attacks, missing rate limits, open CORS), resilience (no DB transactions, no connection pools, no retry logic), and API consistency (phantom types, inconsistent error codes). The result: 3,332 tests across 27 packages with a 100% pass rate.

What is Grantex?

Grantex is OAuth 2.0 for AI agents. When an AI agent calls Salesforce, Jira, or Stripe on behalf of a human, Grantex ensures the agent can only do what it was authorized to do — read contacts, not delete them.

3 SDKs: TypeScript, Python, Go
53 pre-built tool manifests for scope enforcement
Integrations: LangChain, Anthropic, OpenAI Agents, CrewAI, Google ADK, Vercel AI, MCP
W3C Verifiable Credentials, FIDO2/WebAuthn, DID infrastructure
Apache 2.0, IETF Internet-Draft

The Audit

We ran 5 parallel deep-dive audits:

1. Security Audit

Found:

Admin authentication using !== (timing-attack vulnerable)
Zero rate limits on signup, session creation, SAML callbacks
CORS wide open (default Fastify config)
SSO state parameter was plain base64 (forgeable)
JWT exp claim not validated in grant introspection
No scope format validation (could send 10MB scope strings)

Fixed:

crypto.timingSafeEqual() for admin auth
Rate limits on every POST/PATCH/DELETE endpoint
CORS locked to origin: false
SSO state HMAC-signed with timing-safe verification
JWT expiry validated
Scope validation: max 256 chars, max 100 scopes
7 HTTP security headers (HSTS, X-Content-Type-Options, X-Frame-Options, etc.)
1MB body size limit
Input trimming on all string fields

2. Resilience Audit

Found:

No database connection pool settings
Token exchange: 4 sequential DB writes without transaction
Redis errors silently swallowed
No graceful shutdown (workers leaked on SIGTERM)
Health check just returned 200 (didn't check DB or Redis)
No SDK retry logic in any language

Fixed:

Connection pools (max 20, idle 30s, connect 10s, lifetime 30min)
Token exchange wrapped in sql.begin() transaction
Redis error handlers with reconnection logging
Graceful shutdown: SIGTERM → stop workers → close Redis → close DB
Deep health check: SELECT 1 + PING with 2s timeout, 503 on degraded
Config validation on startup (exits on missing DATABASE_URL, REDIS_URL, etc.)
SDK retry with exponential backoff + jitter in TypeScript, Python, and Go
Webhook retry jitter (20% randomization to prevent thundering herd)

3. API Consistency Audit

Found:

SDK types defined pagination fields (total, page, pageSize) that the API never returned
Admin error responses missing code and requestId
HTTP 422 used for parse errors (should be 400)
Inconsistent error formats across routes

Fixed:

SDK types aligned with actual API responses
All error responses standardized: { message, code, requestId }
422 reserved for semantic validation only

4. Observability

Found:

console.log and console.error everywhere
No structured logging
No log levels

Fixed:

Structured pino JSON logging (zero console.* remaining)
LOG_LEVEL env var with dev-mode pino-pretty
Worker child loggers with context bindings

5. Documentation Gaps

Found:

29 API endpoints implemented but undocumented
SDK overview tables missing 6-9 resource clients
4 SDK docs pages missing (Python/Go vault + passports)
No Security Hardening guide
No Operations guide

Fixed:

35 new API reference pages
All overview tables complete (20/20 services)
Security Hardening + Operations guides
SDK retry configuration documented
CHANGELOG updated

The Numbers

Metric	Before	After
Security issues	12	0
Endpoints with rate limits	~5	All
SDK retry logic	None	All 3 languages
Health check depth	Shallow (200 always)	DB + Redis (503 on degraded)
Structured logging	None	Full pino
Test count	~2,800	3,332
Pass rate	~99%	100%
Packages tested	~20	27

Try It

npm install @grantex/sdk    # TypeScript
pip install grantex          # Python
go get github.com/mishrasanjeev/grantex-go  # Go

GitHub: https://github.com/mishrasanjeev/grantex
Docs: https://docs.grantex.dev
Discord: https://discord.gg/QuSk7AeBdg
Security guide: https://docs.grantex.dev/guides/security-hardening
Operations guide: https://docs.grantex.dev/guides/operations

Star the repo if you're building AI agents that need real authorization.

Grantex is Apache 2.0 licensed. IETF Internet-Draft submitted. SOC 2 Type I certified.

Why AI Agents Need Their Own Authorization Protocol (and How We Built One)

Sanjeev Kumar — Sun, 15 Mar 2026 12:17:52 +0000

Every AI agent framework — LangChain, CrewAI, OpenAI Agents SDK, Vercel AI — has the same blind spot: authorization.

Your agent can read emails, book meetings, deploy infrastructure, and spend money. But how does it prove it's allowed to? The answer, for most teams,

is an API key with full access stuffed into an environment variable.

That's not authorization. That's a breach waiting to happen.

## The problem with API keys for agents

API keys were designed for server-to-server auth. They assume a single trusted caller. AI agents break every one of those assumptions:

No scoping. The agent has the same permissions as the key owner.
No consent. The user never approved what the agent can do.
No per-agent identity. You know the key was used, but not which agent used it, or why.
No revocation granularity. One agent misbehaves? Rotate the key. That kills every agent sharing it.
No delegation control. Agent A calls Agent B? You're copy-pasting credentials.
No spending limits. An agent with a cloud API key can provision unlimited resources.

OAuth 2.0 solved this for web apps 15 years ago. IAM solved it for cloud infrastructure. AI agents have nothing.

## Grantex: delegated authorization for agents

Grantex is an open protocol (Apache 2.0) that gives AI agents scoped, time-limited, revocable permissions —
with user consent.

Here's the flow:

Your app requests authorization for a specific agent and specific scopes
The user consents (optionally with FIDO2/WebAuthn passkey)
The agent receives a signed JWT with scoped claims — calendar:read, email:send, etc.
Any service verifies the token offline via JWKS — no callback to an auth server
Tokens expire, can be revoked, and are fully audited


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

  const gx = new Grantex({ apiKey });

  // Request authorization
  const auth = await gx.authorize({
    agentId: 'agent-123',
    userId: 'user-456',
    scopes: ['calendar:read', 'email:send'],
  });

  // Exchange for a grant token
  const { grantToken } = await gx.tokens.exchange({
    code: auth.code,
    agentId: 'agent-123',
  });

  // Verify anywhere — offline
  const grant = await verifyGrantToken(grantToken, {
    jwksUri: 'https://your-server/.well-known/jwks.json',
  });
  // grant.scopes → ['calendar:read', 'email:send']

  Works the same in Python:

  from grantex import Grantex

  gx = Grantex(api_key="...")
  auth = gx.authorize(agent_id="agent-123", user_id="user-456", scopes=["calendar:read"])
  result = gx.tokens.exchange(code=auth.code, agent_id="agent-123")

  And Go:

  client := grantex.New("your-api-key")
  auth, _ := client.Authorize(ctx, grantex.AuthorizeParams{
      AgentID: "agent-123",
      UserID:  "user-456",
      Scopes:  []string{"calendar:read"},
  })

  Delegation: agents authorizing other agents

  This is where it gets interesting. In real agentic systems, agents call other agents. A travel planner agent delegates to a booking agent, which       
  delegates to a payment agent.

  Grantex supports delegation chains with scope narrowing and depth limits:

  const delegation = await gx.grants.delegate({
    parentGrantToken: travelPlannerToken,
    subAgentId: 'booking-agent',
    scopes: ['booking:create'], // narrower than parent
  });

  Revoke the parent? Every child delegation dies automatically. Cascade revocation.

  Budget controls

  Give an agent a spending limit. The protocol enforces it atomically — no race conditions:

  await gx.budgets.allocate({
    grantId,
    amount: 50.00,
    currency: 'USD',
  });

  // Agent tries to spend
  const result = await gx.budgets.debit({
    grantId,
    amount: 12.50,
  });
  // result.remaining → 37.50

  Exceed the budget? The agent gets a 402 INSUFFICIENT_BUDGET. Not a silent failure — a hard stop.

  What else is in the box

  - FIDO2/WebAuthn — passkeys for consent approval
  - W3C Verifiable Credentials — portable agent identity
  - SD-JWT — selective disclosure (agent proves specific claims without revealing everything)
  - Real-time events — SSE/WebSocket streams for authorization events
  - Full audit trail — every action logged and queryable

  Framework integrations

  Drop-in integrations for the frameworks you're already using:

  ┌─────────────────────┬───────────────────────┐
  │      Framework      │        Package        │
  ├─────────────────────┼───────────────────────┤
  │ LangChain           │ @grantex/langchain    │
  ├─────────────────────┼───────────────────────┤
  │ CrewAI              │ grantex-crewai        │
  ├─────────────────────┼───────────────────────┤
  │ OpenAI Agents SDK   │ grantex-openai-agents │
  ├─────────────────────┼───────────────────────┤
  │ Vercel AI           │ @grantex/vercel-ai    │
  ├─────────────────────┼───────────────────────┤
  │ Google ADK          │ grantex-adk           │
  ├─────────────────────┼───────────────────────┤
  │ AutoGen             │ @grantex/autogen      │
  ├─────────────────────┼───────────────────────┤
  │ Express.js          │ @grantex/express      │
  ├─────────────────────┼───────────────────────┤
  │ FastAPI             │ grantex-fastapi       │
  ├─────────────────────┼───────────────────────┤
  │ MCP (Claude/Cursor) │ @grantex/mcp          │
  ├─────────────────────┼───────────────────────┤
  │ Terraform           │ grantex provider      │
  └─────────────────────┴───────────────────────┘

  Standards track

  This isn't a weekend project. The protocol has:

  - An IETF Internet-Draft submitted to the OAuth Working Group
  - A NIST NCCoE public comment filed
  - AuthZEN conformance mapping
  - SOC 2 Type I certification completed
  - A frozen, public https://github.com/mishrasanjeev/grantex/blob/main/SPEC.md

  Try it

  Everything is open source under Apache 2.0:

  - GitHub: https://github.com/mishrasanjeev/grantex
  - Docs: https://docs.grantex.dev
  - Playground: https://grantex.dev/playground

  npm install @grantex/sdk    # TypeScript
  pip install grantex          # Python
  go get github.com/mishrasanjeev/grantex-go  # Go

  If you're building agents that act on behalf of users, I'd love to hear how you're handling authorization today — and what's broken about it.

How to Add Authorization to Your AI Agent (LangChain, CrewAI, OpenAI Agents, and More)

Sanjeev Kumar — Wed, 04 Mar 2026 14:58:01 +0000

How to Add Authorization to Your AI Agent (LangChain, CrewAI, OpenAI Agents, and More)

Tags: ai, security, python, typescript
Series: AI Agent Security
Canonical URL: https://grantex.dev/for/langchain (or leave blank)

AI agents are booking flights, sending emails, and moving money. Most of them run on all-or-nothing API keys.

This is where the web was before OAuth 2.0 — and it's exactly as dangerous as it sounds.

The Problem

When you connect an AI agent to a real service — Stripe, Gmail, Salesforce — you typically give it an API key with full access. The agent can do anything the key allows. There's no scoping ("read emails but don't send"), no audit trail ("what did the agent do?"), and no revocation ("stop this agent NOW").

This was fine when agents were demos. It's not fine when they're in production.

What We Need

The web solved this 15 years ago with OAuth 2.0: users grant scoped, revocable access to applications. But OAuth was designed for human users clicking consent buttons. Agents are different:

Agents spawn sub-agents — a travel agent delegates to a flight booker and a hotel booker
Agents operate autonomously — there's no human in the loop for every API call
Agents chain actions — one agent's output becomes another agent's input

We need OAuth-level security with agent-native primitives.

Enter Grantex

Grantex is an open authorization protocol (Apache 2.0) for AI agents. The core flow:

A human approves a scoped, time-limited grant for an agent
The agent receives a signed JWT it presents to any service
Services verify offline via JWKS — no Grantex account needed
Every action is logged in an append-only, hash-chained audit trail
The human can revoke access instantly — effective in < 1 second

Adding Authorization to Your Agent

LangChain

npm install @grantex/langchain @grantex/sdk

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

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

// 1. Register your agent
const agent = await gx.agents.register({
  name: 'research-agent',
  scopes: ['search:read', 'docs:write'],
});

// 2. Create an authorization request
const auth = await gx.authorize({
  agentId: agent.id,
  userId: 'user_alice',
  scopes: ['search:read', 'docs:write'],
});
// User approves at auth.consentUrl

// 3. Exchange the code for a JWT
const { grantToken } = await gx.tokens.exchange({
  code,
  agentId: agent.id,
});

// 4. Wrap your LangChain tools
const toolkit = new GrantexToolkit({
  client: gx,
  grantToken,
  tools: [searchTool, docsTool],
});

// Tools now verify scopes before executing
const agent = createToolCallingAgent({ llm, tools: toolkit.tools });

What this gives you: Every tool call checks that the agent's JWT has the required scopes. If the agent tries to call a tool it doesn't have permission for, it gets a clear error — not a silent failure.

Full LangChain guide →

CrewAI

pip install grantex-crewai grantex

from grantex import Grantex
from grantex_crewai import GrantexCrewTools

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

# Each crew member gets its own scoped token
researcher = GrantexCrewTools(
    client=gx,
    grant_token=researcher_token,  # "search:read" only
    tools=[search_tool],
)

writer = GrantexCrewTools(
    client=gx,
    grant_token=writer_token,  # "docs:write" only
    tools=[write_tool],
)

The researcher can search but not write. The writer can write but not search. Revoke any crew member without stopping the whole crew.

Full CrewAI guide →

OpenAI Agents SDK

pip install grantex-openai-agents grantex

from grantex_openai_agents import GrantexTools

tools = GrantexTools(
    client=gx,
    grant_token=token,
    tools=[search_tool, email_tool],
)

agent = Agent(name="assistant", tools=tools.wrapped)

Full OpenAI Agents guide →

Google ADK

pip install grantex-adk grantex

from grantex_adk import GrantexADKTools

tools = GrantexADKTools(
    client=gx,
    grant_token=token,
    tools=[calendar_tool],
)

agent = Agent(model="gemini-2.0-flash", tools=tools.wrapped)

Full Google ADK guide →

Vercel AI SDK

npm install @grantex/vercel-ai @grantex/sdk

import { createGrantexTools } from '@grantex/vercel-ai';

const tools = createGrantexTools({
  client: gx,
  grantToken: token,
  tools: { search: searchTool, email: emailTool },
});

const result = await generateText({
  model: openai('gpt-4o'),
  tools,
  prompt: 'Book the cheapest flight to NYC',
});

Edge-compatible. Works with streaming. TypeScript-first.

Full Vercel AI guide →

Protecting Your API (Service Side)

If you're building the API that agents call, you need to verify their tokens.

Express.js

npm install @grantex/express

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

app.use('/api', grantexMiddleware({
  jwksUrl: 'https://your-auth/.well-known/jwks.json',
}));

app.get('/api/emails', requireScopes(['email:read']), (req, res) => {
  console.log(req.grantex.agent);  // agent DID
  console.log(req.grantex.scopes); // ['email:read']
  res.json({ emails: [] });
});

Sub-millisecond overhead. JWKS cached locally. Express guide →

FastAPI

pip install grantex-fastapi

from grantex_fastapi import GrantexAuth, GrantContext

auth = GrantexAuth(jwks_url="https://your-auth/.well-known/jwks.json")

@app.get("/api/emails")
async def list_emails(
    grant: GrantContext = Depends(auth.require_scopes(["email:read"]))
):
    return {"emails": []}

Async-native. Pydantic models. OpenAPI integration. FastAPI guide →

Beyond Scoping: What Else You Get

Delegation chains — A travel agent can delegate narrower permissions to a flight-booking sub-agent. The delegation depth is tracked in the JWT. Revoking the parent cascades to all children.

Budget controls — Set spending limits per agent. When the budget hits a threshold (50%, 80%), you get an alert. When it's exhausted, the agent is automatically cut off.

Real-time event streaming — SSE and WebSocket streams for grant creation, token issuance, budget alerts. Build dashboards and monitoring.

Policy engine — Pluggable authorization backends: builtin rules, OPA, or Cedar. Sync policies from git.

End-user permission dashboard — Users can view and revoke agent access from a self-serve dashboard. Embed it in your app.

Getting Started

# TypeScript / Node.js
npm install @grantex/sdk

# Python
pip install grantex

# Go
go get github.com/mishrasanjeev/grantex-go

Website: grantex.dev
Docs: docs.grantex.dev
GitHub: github.com/mishrasanjeev/grantex
Playground: grantex.dev/playground — try it in your browser, no signup

The protocol spec is public and frozen at v1.0. Everything is Apache 2.0. No vendor lock-in — verification is offline via JWKS.

What authorization challenges are you hitting with AI agents? I'd love to hear about your use cases in the comments.

Why AI Agents Need Their Own Authorization Protocol (and how we built one)

Sanjeev Kumar — Sun, 01 Mar 2026 06:48:13 +0000

AI agents are shipping fast. They book flights, send emails, move money, and deploy code. But here is the uncomfortable truth: most of them operate with all-or-nothing API keys and zero audit trail. If an agent goes rogue, you find out after the damage is done.

We built Grantex to fix that.

The Problem

Every time you click "Sign in with Google" or grant an app access to your calendar, OAuth 2.0 is doing the work. It has been the backbone of delegated authorization for over a decade. So why can't we just use it for AI agents?

The short answer: agents are not apps.

OAuth 2.0 was designed for human users clicking "Allow" on a consent screen. It works brilliantly for that. But agents operate autonomously, spawn sub-agents, and chain actions across services. OAuth was never designed for:

Agent identity -- agents need their own cryptographic identity, not borrowed user credentials.
Delegation chains -- a parent agent granting a sub-agent a narrower set of permissions.
Action-level auditing -- knowing exactly what an agent did, not just that it authenticated.
Real-time revocation -- killing a misbehaving agent's access in milliseconds, not minutes.

The Four Gaps in Detail

1. Agent Identity vs. App Identity

OAuth issues tokens to registered applications. An app has a client_id, a redirect URI, and a set of scopes. This model assumes a fixed, known piece of software.

AI agents are different. A single orchestrator might spawn dozens of sub-agents at runtime, each with a different purpose. These agents need their own cryptographic identity -- not a shared client_id. Grantex assigns each agent a DID (Decentralized Identifier) backed by a key pair. The agent's identity is verifiable, rotatable, and independent of the platform it runs on.

2. Scope Delegation Chains

OAuth supports a flat model: a user grants scopes to an app, and that is the end of the story. But agents delegate work to other agents. A "research assistant" agent might call a "web search" sub-agent and a "summarizer" sub-agent, each of which should only get the scopes it actually needs.

Grantex models this explicitly. When a parent agent delegates to a child, the child's grant token carries parentAgt, parentGrnt, and delegationDepth claims. The child's scopes must be a strict subset of the parent's. This is not a convention -- it is enforced at the protocol level.

Root user grants: [files:read, files:write, email:send]
  └─ Parent agent:  [files:read, files:write]  (delegationDepth: 0)
       └─ Child agent:  [files:read]            (delegationDepth: 1)

If the parent's grant is revoked, every child grant in the chain is automatically invalidated.

3. Real-Time Revocation

OAuth token revocation is defined in RFC 7009, but it is advisory. Resource servers are free to keep accepting a token until it expires. For a 1-hour access token, that is a 1-hour window of exposure.

With agents performing high-stakes actions autonomously, you cannot afford that window. Grantex supports both offline verification (fast JWT validation) and online verification that checks revocation state in real time. When you revoke a grant, the very next verification call returns valid: false.

4. Action-Level Audit Trails

OAuth gives you an access log at the authorization server. You know when a token was issued and when it was refreshed. You do not know what happened next.

Grantex includes a first-class audit subsystem. Every action an agent performs can be logged, and the entries are append-only and hash-chained -- each entry references the hash of the previous one, making tampering detectable. You can query the full trail filtered by agent, grant, principal, or time range.

The Compliance Dimension

This is not just a technical nicety. The EU AI Act (effective August 2025) requires that high-risk AI systems maintain logs of their operation, support human oversight, and provide transparency about their decision-making. Grantex's audit trail, scoped grants, and real-time revocation map directly onto these requirements.

Similarly, SOC 2 auditors want to see evidence that access is scoped, time-limited, and revocable. Grant tokens with explicit expiration, scope restrictions, and revocation support provide that evidence out of the box.

Why Not Extend OAuth?

We considered it. The problem is that the primitives do not exist. OAuth has no concept of agent identity, delegation depth, or hash-chained audit logs. Bolting these onto OAuth would mean a constellation of non-standard extensions that no existing library supports.

Grantex is a clean-sheet protocol that speaks the same language as OAuth where it makes sense (JWTs, JWKs, RS256, scopes, authorization codes) but adds the agent-specific primitives as first-class concepts. If you know OAuth, Grantex will feel familiar. But it will also handle the cases OAuth was never designed for.

What It Looks Like in Code

Here is the full flow in TypeScript:

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

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

// 1. Register an agent
const agent = await gx.agents.register({
  name: 'travel-booking-agent',
  description: 'Books flights and hotels for users',
  scopes: ['flights:book', 'hotels:search'],
});

// 2. Request authorization from a user
const auth = await gx.authorize({
  agentId: agent.id,
  userId: 'user_alice',
  scopes: ['flights:book', 'hotels:search'],
  callbackUrl: 'https://app.example.com/callback',
});
// → redirect user to auth.consentUrl

// 3. Exchange the authorization code for a grant token
const token = await gx.tokens.exchange({
  code: callbackCode,
  agentId: agent.id,
});

// 4. Verify the token before acting
const result = await gx.tokens.verify(token.grantToken);
console.log(result.scopes); // ['flights:book', 'hotels:search']

// 5. Log every action to the audit trail
await gx.audit.log({
  agentId: agent.id,
  grantId: token.grantId,
  action: 'flight.booked',
  status: 'success',
  metadata: { airline: 'Air India', amount: 420 },
});

The same flow works in Python:

from grantex import Grantex, ExchangeTokenParams

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

agent = client.agents.register(
    name="travel-booking-agent",
    scopes=["flights:book", "hotels:search"],
)

auth = client.authorize(
    agent_id=agent.id,
    user_id="user_alice",
    scopes=["flights:book", "hotels:search"],
)
# redirect user to auth.consent_url

token = client.tokens.exchange(
    ExchangeTokenParams(code=callback_code, agent_id=agent.id)
)
print(token.scopes)  # ('flights:book', 'hotels:search')

What Ships Today

Protocol spec v1.0 (final) -- the full specification is public and frozen.
TypeScript SDK (@grantex/sdk) and Python SDK (grantex) -- production-ready.
Go SDK (grantex-go) -- production-ready.
8 framework integrations -- LangChain, AutoGen, CrewAI, Vercel AI, OpenAI Agents SDK, Google ADK, an MCP server for Claude Desktop, and Express.js + FastAPI middleware.
CLI (@grantex/cli) -- manage agents, grants, and tokens from your terminal.
Enterprise features -- policy engine, SCIM/SSO, anomaly detection, compliance exports, and Stripe billing.
Full API Reference with interactive docs and a Postman collection.

Get Started

Install the SDK:

npm install @grantex/sdk        # TypeScript / Node.js
pip install grantex             # Python
go get github.com/mishrasanjeev/grantex-go  # Go
npm install -g @grantex/cli     # CLI

Then pick your path:

Quickstart guide -- up and running in under 5 minutes.
Sign up for a free account -- get your API key.
GitHub repository -- star, fork, contribute.
Full documentation -- guides, SDK reference, examples.
API Reference -- all 56 endpoints with schemas.
Protocol specification -- the full v1.0 spec.
Homepage -- project overview.

We believe that as agents become more capable, proper authorization becomes more critical, not less. Grantex is our answer to that challenge.

Grantex is open source (Apache 2.0). If you're building agent systems and care about authorization, we'd love your feedback -- open an issue or star the repo.