Grantex

Open-Source AI Agent Authorization and Delegated Access

What OAuth 2.0 is to humans, Grantex is to agents.

License: Apache 2.0 Spec Version IETF Draft CI npm PyPI npm downloads GitHub Stars Docs MCP Tool Server MCP Auth DPDP Mapping EU AI Act Mapping

Docs | Quickstart | Release JSON | LLM Index | Spec | IETF Draft

What is Grantex?

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. Use Grantex when an AI agent acts for a person or organization and a relying service must verify exactly what that agent may do.

Open Agentic Commerce Protocol (OACP) Authority

Open Agentic Commerce Protocol (OACP) is Grantex's agentic-commerce trust and artifact-authority layer. Grantex governs OACP policy, internal artifact issuance or refusal, verification, and compatibility adapters. AgenticOrg owns buyer and seller AI-agent runtime, merchant self-service onboarding, Shopify connector runtime, future merchant connector setup intent, buyer sessions, channel bridges, OACP cache, and provider-owned capability verification.

Merchant systems such as Shopify, future WooCommerce/ERP sources, POS systems, and provider systems remain the source of record. Provider, bank, POS, and payment rails own mandate, payment, and in-store execution. Grantex signs and verifies artifacts; it is not a merchant connector runtime or a toll booth for every buyer and seller message.

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 -->|OACP artifacts or blockers| agentic
  agentic --> buyer[Buyer surfaces]
  agentic -->|capability check or handoff| provider[Pine Labs Plural/P3P, bank/POS/provider rails]

Start with the OACP runtime launch closure PRD, OACP authority overview, merchant self-service config boundary, truth inventory, AgenticOrg integration guide, POS bridge boundary, and operator runbook. The older Commerce V1 overview remains historical/contextual and should not be used to imply that Grantex owns AgenticOrg merchant connector runtime.

Current Releases

Grantex components are independently versioned. The protocol specification remains v1.0 Final; SDK, MCP package, and roadmap milestone versions are separate release lines and do not represent a monorepo-wide version.

Current public releases, verified 2026-07-12:

Known published-package limits: Go SDK v0.1.10 has documented Agent/Audit read, write, filter, query-encoding, and list-metadata limitations. MCP Auth 2.0.2 keeps authorization codes in process memory, does not render consent, and has an incomplete Grantex code handoff. See the release-status guide for exact workarounds and deployment boundaries.

Repository development status (unreleased, July 14, 2026): source on main corrects all documented Go Agent/Audit contract gaps, removes no-op audit filters and phantom list metadata, and URL-encodes query values. The auth service also enforces Redis-backed Free/Pro/Enterprise developer budgets of 100/500/2,000 requests per minute on API-key routes handled by the standard auth plugin. Custom-auth quota policy remains open. No corrected Go tag or managed-service rollout is claimed; the public versions and workarounds above remain authoritative.

Omit a version pin to install the registry's current latest release. See the release-status documentation, COMPATIBILITY.md for the full package matrix, and CHANGELOG.md for release notes.

• @grantex/gemma: Offline consent bundles and on-device verification examples
• MCP Authorization Server (@grantex/mcp-auth): Published OAuth 2.1 + PKCE endpoint package; review the documented 2.0.2 single-process, consent, and token-exchange limitations
• MCP Tool Server (@grantex/mcp): Agent-facing Grantex tools for MCP clients
• @grantex/dpdp: DPDP Act 2023 and EU AI Act control mappings
• Trust Registry: Public DID verification registry — grantex.dev/registry
• grantex verify: Token inspection CLI — no account needed
• Anomaly Detection: Four implemented SQL-backed checks, lifecycle APIs, and stored rule/channel configuration; notification delivery requires a host worker

SDK quickstart

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.3.14               # 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 evaluation
npm install -g @grantex/cli                         # Optional CLI tooling

29 packages across TypeScript, Python, and Go. Integrations for Anthropic SDK, LangChain, OpenAI Agents SDK, Google ADK, Strands Agents SDK, CrewAI, Vercel AI, AutoGen, MCP, Express.js, FastAPI, and Terraform. Use the compatibility matrix for versions, the changelog for release notes, and GitHub Actions for current CI status. Fully self-hostable. Apache 2.0.

The Problem

AI agents are booking travel, sending emails, deploying code, and spending money — on behalf of real humans. But:

• No scoping — agents get the same access as the key owner
• No consent — users never approve what the agent can do
• No per-agent identity — you know the key was used, but not which agent or why
• No revocation granularity — one agent misbehaves, rotate the key, kill everything
• No delegation control — Agent A calls Agent B? Copy-paste credentials
• No spending limits — an agent with a cloud API key can provision unlimited resources

OAuth and IAM provide essential foundations, but many agent deployments still rely on shared credentials that do not identify the individual agent or encode its delegated authority.

How It Works

Quickstart

1. Register your 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. Request authorization from a user

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. Exchange the authorization code for a grant token

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

4. Verify the token and use it

// 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. Record the action at the execution boundary

// 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. Verify a token (service-side)

// 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. Give users control over their permissions

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

The Grant Token

Grantex tokens are standard JWTs (RS256) extended with agent-specific claims. Any service can verify their signatures locally using the issuer's published JWKS. The provided verifiers retrieve those keys from the configured JWKS URL, so applications should account for network availability, caching, and key rotation:

{
  "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"
}

Delegation claims (present on sub-agent tokens):

Multi-Agent Delegation

Grantex supports multi-agent pipelines where a root agent spawns sub-agents with narrower scopes. Sub-agent tokens carry a full delegation chain that any service can inspect.

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

Constraints enforced by the protocol:

• Sub-agent scopes must be a strict subset of the parent's scopes — scope escalation is rejected with 400
• Sub-agent token expiry is min(parent expiry, requested expiry) — sub-agents can never outlive their parent
• Revoking a root grant cascades to all descendant grants atomically

Advanced Features

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

// 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' });

// Register a passkey for an end-user (called from the browser)
const options = await grantex.webauthn.registerOptions({ principalId: 'user_abc123' });
// Pass options to navigator.credentials.create() in the browser
const credential = await navigator.credentials.create({ publicKey: options });
await grantex.webauthn.registerVerify({ challengeId: options.challengeId, response: credential });

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

# Enable FIDO for your developer account
from grantex import UpdateDeveloperSettingsParams, WebAuthnRegistrationVerifyParams

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

# Register a passkey (server-side portion)
options = client.webauthn.register_options(principal_id="user_abc123")
# Browser performs navigator.credentials.create() and sends response back
result = client.webauthn.register_verify(WebAuthnRegistrationVerifyParams(
    challenge_id=options.challenge_id,
    response=credential_response,
))

# List and manage credentials
creds = client.webauthn.list_credentials("user_abc123")
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

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()

// Register a consent notice
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' }],
});

// Create a consent record linked to a 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',
});

// Data principal exercises right to access (DPDP §11)
const { records } = await grantex.dpdp.listPrincipalRecords('[email protected]');

// Withdraw consent — optionally revoke grant and delete data
const withdrawal = await grantex.dpdp.withdrawConsent(record.recordId, {
  reason: 'No longer needed',
  revokeGrant: true,
  deleteProcessedData: true,
});

// File a grievance (DPDP §13(6))
const grievance = await grantex.dpdp.fileGrievance({
  dataPrincipalId: '[email protected]',
  type: 'data_breach',
  description: 'Unauthorized data access',
});

// Request data erasure (DPDP §11)
const erasure = await grantex.dpdp.requestErasure('[email protected]');

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

# Python SDK
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]")

Scope Enforcement

Enforce tool-level permissions on any connector — define your own manifests or use the 53 pre-built ones.

Quick Start

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"

Permission Hierarchy

Bring your own manifests: define inline, load from JSON files, load from a directory, or auto-generate from source code via CLI. 53 pre-built manifests included: Salesforce, HubSpot, Jira, Stripe, SAP, S3, Gmail, Slack, GitHub, and 44 more — use as-is or as a starting point.

Framework helpers: wrapTool() wraps LangChain tools with automatic scope enforcement. createGrantexTool() covers TypeScript agent framework helpers including Strands Agents SDK. create_grantex_tool() covers Python OpenAI Agents SDK, Google ADK, and Strands Agents SDK tools. enforceMiddleware() adds one-line enforcement to Express/Fastify routes. FastAPI uses the GrantexEnforcer dependency.

See the Scope Enforcement Guide for full documentation.

Local Development

Start the full stack with one command:

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

Two API keys are seeded automatically:

Sandbox mode is designed for testing. With a sandbox key, POST /v1/authorize returns a code in the response body — no redirect required:

# 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>"}'

Developer portal is available at grantex.dev/dashboard — sign up or enter an API key to manage agents, grants, policies, anomalies, compliance exports, and billing from the browser.

For local development, the auth service also serves a lightweight dashboard at http://localhost:3001/dashboard.

See the self-hosting guide for production deployment guidance, or DEPLOYMENT.md for the complete deployment reference (system requirements, environment variables, Docker/Kubernetes/Cloud Run options, security checklist, monitoring). Python dependencies are in requirements.txt.

Why an Open Standard?

Grantex is built as an open protocol, not a closed SaaS product. Here's why that matters:

Model-neutral. Grantex operates at the SDK or protected-service boundary rather than depending on one model provider. The project documents use with OpenAI, Anthropic, Google, Llama, and Mistral models.

Framework-native. First-class integrations for LangChain, AutoGen, CrewAI, OpenAI Agents SDK, Google ADK, Strands Agents SDK, and plain code. Install one package, get Grantex in your existing stack.

Offline-verifiable signatures. Services verify token signatures locally using published JWKS. Applications should plan for JWKS retrieval and key rotation; availability during an issuer outage depends on their verifier's cache behavior.

Compliance-oriented controls. The EU AI Act, GDPR, and emerging US AI regulations will mandate auditable agent actions. Grantex provides technical controls that can support those programs from day one.

Scope Naming Convention

Grantex defines a standard scope format: resource:action[:constraint]

Service providers implement scope definitions for their APIs. Agents declare which scopes they need. Users see plain-language descriptions, never raw scope strings.

Integrations

The primary SDK versions below are registry-verified as of 2026-07-12. For integration packages, “Published package” identifies a public package surface; check its registry page and compatibility notes before choosing a version.

Community x402 services

• JMT x402 Agent Tools provides paid Base-mainnet tools for search, analysis, market data, filings, company intelligence, and news. Query its discovery endpoint for the current tool catalog and pricing.

Framework Quick Examples

Express.js — grant token verification + scope-based authorization:

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 — dependency injection with scope enforcement:

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 — scope-enforced tools + audit callbacks:

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 — scope checked at construction time:

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

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

AutoGen / OpenAI function calling:

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

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

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

CrewAI (Python):

from grantex_crewai import GrantexTool

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

OpenAI Agents SDK (Python):

from grantex_openai_agents import create_grantex_tool

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

Google ADK (Python):

from grantex_adk import create_grantex_tool

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

Strands Agents SDK (Python):

from grantex_strands import create_grantex_tool

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

CLI (90+ commands, all support --json for AI agent / scripting use):

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 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 compliance (11 subcommands)
grantex dpdp consent create --grant-id grnt_... --principal-id [email protected]
grantex dpdp consent get <recordId>
grantex dpdp consent list --principal-id [email protected]
grantex dpdp consent withdraw <recordId> --reason "No longer needed"
grantex dpdp notices create --notice-id privacy-v1 --version 1.0 --title "Privacy Notice"
grantex dpdp grievances file --principal-id [email protected] --type violation
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'

Interactive Playground

Try the full Grantex authorization flow live in your browser — no signup required:

grantex.dev/playground

Walk through all 7 steps of the protocol: register an agent, authorize, exchange tokens, verify, refresh, revoke, and verify revocation. Uses sandbox mode with your API key.

Examples

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         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   │
                └──────────────────────────┘

Product Roadmap

The current product roadmap prioritizes a 2026.08 production-trust baseline: durable MCP authorization, primary-SDK parity and release safety, revocation-aware enforcement, plan throughput, and production Commerce consent. Repository progress is recorded under Unreleased; the release-status guide, compatibility matrix, and package-specific documentation remain authoritative for published versions, deployment status, and limitations. The labels below are historical source milestones, not release or production-readiness claims.

Contributing

Grantex is open-source and welcomes contributions:

1. Report bugs — open a GitHub Issue with reproduction steps
2. Propose features — open a GitHub Discussion with your use case
3. Build new integrations — add Grantex support to your favorite framework
4. Improve docs — better examples, tutorials, and translations

Read CONTRIBUTING.md before submitting a PR.

Standards & Compliance

Full compliance matrix: docs.grantex.dev/guides/compliance-matrix

Trusted By

Using Grantex in production? Open a PR to add your company here.

FAQ

Is this just another auth library?
Human identity systems and Grantex solve different layers. Human auth establishes who the person is; Grantex carries the scoped authority that person or organization delegated to a specific agent. Current revocation requires an online state check or synchronized revocation data at the enforcement point.

Why not just use OAuth 2.0?
OAuth 2.0 was designed for "user grants app permission to access their data." Agents introduce new requirements: the agent needs a verifiable identity separate from its creator, grants need to be chainable across multi-agent pipelines, and every autonomous action must be attributable and auditable. We extend OAuth 2.0 concepts but add the agent-specific primitives it lacks.

What about MCP (Model Context Protocol)?
MCP connects clients to tools and resources and defines optional OAuth-based authorization for HTTP transports. Grantex adds agent-specific delegated authority at the tool or service boundary: which agent may perform which action for which principal. The two layers are complementary.

Who owns the standard?
The v1.0 protocol specification is open (Apache 2.0), and Grantex Inc. maintains the reference implementation. An active -01 document is published as an individual IETF Internet-Draft; that publication is not working-group adoption or IETF endorsement.

Can I self-host?
Yes. The reference implementation is fully open-source. Docker Compose deploy in one command. See DEPLOYMENT.md for the complete guide or the self-hosting docs.

License

Protocol specification and SDKs: Apache 2.0