Grantex

Open-Source AI Agent Authorization and Delegated Access

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

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]

Area	Current posture
Grantex C6Z authority route	Implemented at `POST /v1/commerce/oacp/c6z/authority-requests` for allowlisted AgenticOrg tenants.
Artifact families	11 internal OACP families are issued or refused with source lineage, TTL, freshness, revocation posture, blocked capabilities, non-sensitive evidence refs, and signature metadata.
Protocol adapters	Schema.org, UCP-style, ACP-style, AP2-style, A2A, MCP, and OpenAPI mappings are compatibility mappings derived from OACP artifacts.
AgenticOrg runtime	Merchant self-service config, Seller onboarding, Shopify sync, future connector/provider intent capture, cache, buyer Q&A, bridges, and provider capability verification live in AgenticOrg.
Payment/order/POS execution	Outside OACP artifact authority. Provider, POS, and merchant systems must execute and confirm; agents must not invent success.
Historical Commerce V1 docs	Retained for context, but superseded for the AgenticOrg OACP runtime split.

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:

Component	Public version	Reproducible install
TypeScript SDK	`@grantex/sdk` `0.3.13`	`npm install @grantex/[email protected]`
Python SDK	`grantex` `0.3.14`	`python -m pip install grantex==0.3.14`
Go SDK	`github.com/mishrasanjeev/grantex-go` `v0.1.10` (Go 1.26.1+)	`go get github.com/mishrasanjeev/[email protected]`
MCP Authorization Server	`@grantex/mcp-auth` `2.0.2`	`npm install @grantex/[email protected] @grantex/[email protected]`

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

Claim	Meaning
`sub`	The end-user who authorized this agent
`agt`	The agent's DID — cryptographically verifiable identity
`dev`	The developer org that built the agent
`scp`	Exact scopes granted — services should check these
`jti`	Unique token ID — used for grant-state and revocation checks
`grnt`	Grant record ID — links token to the persisted grant
`aud`	Intended audience (optional) — services should reject tokens with a mismatched `aud`

Delegation claims (present on sub-agent tokens):

Claim	Meaning
`parentAgt`	DID of the parent agent that spawned this sub-agent
`parentGrnt`	Grant ID of the parent grant — full delegation chain is traceable
`delegationDepth`	How many hops from the root grant (root = 0)

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

Enterprise SSO

Grantex provides OIDC and SAML 2.0 enterprise SSO with multiple identity-provider connections, email-domain routing, enforcement, JIT provisioning, and group-to-scope mapping from identity-provider claims. The LDAP surface is a direct-bind preview: it authenticates a supplied directory identity but does not search directories or retrieve LDAP groups.

Key capabilities:

Multi-IdP connections - Configure multiple OIDC and SAML 2.0 identity providers per organization; LDAP connection records support the direct-bind preview
OIDC Discovery + JWKS verification — Automatic endpoint discovery and cryptographic ID token verification
SAML 2.0 — Full SAML response parsing with certificate-based signature verification
LDAP / Active Directory preview - Direct-bind authentication only; directory search and LDAP group retrieval are not implemented
Domain-based routing — Automatically route users to the correct IdP based on their email domain
JIT provisioning — Auto-create or update principals on first SSO login
Group-to-scope mapping - Map OIDC or SAML group/role claims to Grantex scopes; this does not retrieve LDAP groups
SSO enforcement — Require SSO authentication for all users in an organization
Session management — Track, list, and revoke active SSO sessions

TypeScript

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

Python

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

CLI

# 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

FIDO2 / WebAuthn

Grantex supports passkey-based human presence verification using the FIDO2/WebAuthn standard. When enabled, end-users prove they are physically present during the consent flow by authenticating with a passkey (biometric, security key, or platform authenticator). This raises the assurance level of every grant from "user clicked approve" to "user was cryptographically verified."

How It Works

Developer enables FIDO — Set fidoRequired: true on your developer profile via PATCH /v1/me
User registers a passkey — During the first consent flow, the user registers a FIDO2 credential (fingerprint, Face ID, YubiKey, etc.)
User authenticates on consent — On subsequent authorization requests, the user completes a WebAuthn assertion challenge instead of a simple button click
FIDO evidence embedded in grants — The assertion result is recorded in the grant and can be embedded in Verifiable Credentials as cryptographic proof of human presence

SDK Usage

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

WebAuthn API Endpoints

Method	Endpoint	Description
`POST`	`/v1/webauthn/register/options`	Generate passkey registration options
`POST`	`/v1/webauthn/register/verify`	Verify registration and store credential
`GET`	`/v1/webauthn/credentials`	List WebAuthn credentials for a principal
`DELETE`	`/v1/webauthn/credentials/:id`	Delete a credential
`POST`	`/v1/webauthn/assert/options`	Generate assertion options for consent
`POST`	`/v1/webauthn/assert/verify`	Verify assertion during consent
`PATCH`	`/v1/me`	Update developer settings (FIDO config)

Verifiable Credentials

Grantex can issue W3C Verifiable Credentials (VCs) alongside standard JWTs. While JWTs are optimized for real-time authorization, VCs provide a portable, tamper-evident, standards-based proof of authorization that can be presented to any verifier — including systems outside the Grantex ecosystem.

Why VCs Matter for Agents

In agentic commerce, an agent acting on your behalf needs to prove its authorization to third-party services that may not integrate with Grantex directly. A Verifiable Credential is a self-contained, cryptographically signed document that any party can verify using the issuer's published DID document — no API calls, no accounts, no trust relationships required.

How It Works

When exchanging an authorization code for a grant token, pass credentialFormat: "vc-jwt" to receive a Verifiable Credential alongside the standard grant token:

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

Credential Types

Type	Description
`AgentGrantCredential`	Issued for direct grants — attests that a principal authorized an agent with specific scopes
`DelegatedGrantCredential`	Issued for delegated grants — includes the full delegation chain

Verifying a VC

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)

Revocation via StatusList2021

Grantex implements the W3C StatusList2021 revocation mechanism. Each credential references a status list entry. When a grant is revoked, the corresponding bit in the status list is flipped, and any verifier checking the credential sees it as revoked.

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

FIDO Evidence in VCs

When FIDO is enabled and the user completes a WebAuthn assertion during consent, the VC includes a fidoEvidence field that cryptographically proves human presence at the time of authorization. This is compatible with the Mastercard Verifiable Intent specification for agentic commerce.

DID Infrastructure

Grantex publishes a W3C DID document at /.well-known/did.json (did:web:grantex.dev). This document contains the public keys used to sign Verifiable Credentials, enabling any party to verify credentials without contacting Grantex:

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

Verifiable Credentials API Endpoints

Method	Endpoint	Description
`GET`	`/v1/credentials/:id`	Retrieve a Verifiable Credential
`GET`	`/v1/credentials`	List Verifiable Credentials
`POST`	`/v1/credentials/verify`	Verify a VC-JWT
`GET`	`/v1/credentials/status/:id`	StatusList2021 credential
`GET`	`/.well-known/did.json`	W3C DID document

MPP Agent Identity

MPP (Machine Payments Protocol) defines HTTP 402 payment flows for software clients. Grantex can attach an AgentPassportCredential based on W3C Verifiable Credentials 2.0 so a configured merchant can verify agent, principal, category, amount-limit, expiry, and delegation claims after obtaining the issuer keys and current status data. The credential carries authorization context; it does not prove that a payment settled, an order was approved, or a provider accepted the transaction.

Why Agent Passports?

A wallet or payment-source identifier may not tell a merchant which internal agent is acting, which principal delegated authority, or which policy limits apply. An agent passport can supply that context when both sides integrate and enforce it.

The current Grantex passport shape uses Ed25519 signatures, a W3C VC 2.0 data model, configured purchase categories, transaction ceilings, expiry, delegation context, and StatusList2021-style status data. A relying merchant must still validate the issuer, refresh keys and status according to its risk policy, enforce the claims at the protected action, and run its own payment, fraud, sanctions, order, and settlement controls.

How It Works

Step	Who	What
1. Issue	Authorized application	Requests an `AgentPassportCredential` with configured categories, amount ceiling, delegation context, and expiry
2. Store	Agent host	Stores the credential as sensitive authorization material
3. Present	Agent host	Attaches the credential to a supported MPP request when the integration is configured
4. Verify	Merchant service	Verifies signature, issuer, expiry, category, amount, and sufficiently current status data
5. Decide	Merchant and payment systems	Apply merchant policy plus independent payment, order, provider, and settlement checks before execution
6. Record	Each participating system	Records the events it is configured to observe; credential verification alone is not an execution or settlement audit log

Verification boundary: cached keys can support local signature checks after retrieval. Current revocation requires refreshed status data, and cache policy determines how quickly a relying service observes a change.

Credential Structure

Field	Description
`id`	`urn:grantex:passport:<ulid>`
`issuer`	`did:web:grantex.dev`
`credentialSubject.id`	Agent DID (`did:grantex:ag_...`)
`credentialSubject.humanPrincipal`	DID of the authorizing human
`credentialSubject.organizationDID`	Org DID (`did:web:<domain>`)
`credentialSubject.grantId`	Links to underlying Grantex grant
`credentialSubject.allowedMPPCategories`	`inference`, `compute`, `data`, `storage`, `search`, `media`, `delivery`, `browser`, `general`
`credentialSubject.maxTransactionAmount`	`{ amount, currency }` ceiling per transaction
`credentialSubject.delegationDepth`	Inherited from grant delegation chain
`credentialStatus`	StatusList2021 revocation entry
`proof`	Ed25519Signature2020

Issue a Passport

TypeScript:

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:

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

Attach to MPP Requests

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

Verify on the Merchant Side

Standalone verification:

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

Express middleware (one-liner):

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

Trust Registry

Query any organization's verified trust level — no authentication required:

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"

Revocation

Revoking a passport updates server-side status immediately. Local verifiers observe the change only after an online revocation check or status-data refresh, so cached results can lag:

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

Error Codes

Code	HTTP	Description
`PASSPORT_EXPIRED`	403	Credential `validUntil` has passed
`PASSPORT_REVOKED`	403	StatusList2021 bit is set
`INVALID_SIGNATURE`	403	Signature verification failed
`UNTRUSTED_ISSUER`	403	Issuer DID not in trusted list
`CATEGORY_MISMATCH`	403	Categories don't cover required service
`AMOUNT_EXCEEDED`	403	Max amount below required threshold
`MISSING_PASSPORT`	403	No `X-Grantex-Passport` header
`MALFORMED_CREDENTIAL`	403	Invalid base64url or missing VC fields

MPP Agent Identity API Endpoints

Method	Endpoint	Auth	Description
`POST`	`/v1/passport/issue`	API key	Issue AgentPassportCredential
`GET`	`/v1/passports`	API key	List passports (filter by agentId, grantId, status)
`GET`	`/v1/passport/:id`	API key	Retrieve passport by ID
`POST`	`/v1/passport/:id/revoke`	API key	Revoke passport (StatusList2021)
`GET`	`/v1/trust-registry/:orgDID`	None	Look up org trust record (public)
`GET`	`/v1/trust-registry`	API key	List all trust records (admin)

See packages/mpp/ for full package docs. Demo: grantex.dev/mpp-demo.

SD-JWT Selective Disclosure

Grantex supports SD-JWT (Selective Disclosure JWT) for privacy-preserving credential presentation. While a standard VC-JWT reveals all claims to every verifier, SD-JWT lets the holder choose exactly which fields to disclose — keeping everything else hidden.

Why SD-JWT?

In agentic commerce, different verifiers need different levels of information. A payment processor needs to know the agent's scopes and budget, but not the principal's identity. A compliance auditor needs the principal and timestamps, but not the scopes. SD-JWT enables minimum-disclosure presentations that satisfy each verifier's requirements without over-sharing.

How It Works

When exchanging an authorization code, pass credentialFormat: "sd-jwt" to receive an SD-JWT credential:

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

Creating a Presentation

The holder selects which claims to disclose when presenting to a verifier:

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

SD-JWT Format

An SD-JWT consists of: <issuer-jwt>~<disclosure1>~<disclosure2>~...~

Each disclosure is a base64url-encoded JSON array [salt, claim-name, claim-value].

Grantex

README

Grantex

Open-Source AI Agent Authorization and Delegated Access

What is Grantex?

Open Agentic Commerce Protocol (OACP) Authority

Current Releases

SDK quickstart

The Problem

How It Works

Quickstart

1. Register your agent

2. Request authorization from a user

3. Exchange the authorization code for a grant token

4. Verify the token and use it

5. Record the action at the execution boundary

6. Verify a token (service-side)

7. Give users control over their permissions

Python SDK

The Grant Token

Multi-Agent Delegation

Advanced Features

Enterprise SSO

TypeScript

Python

CLI

FIDO2 / WebAuthn

How It Works

SDK Usage

WebAuthn API Endpoints

Verifiable Credentials

Why VCs Matter for Agents

How It Works

Credential Types

Verifying a VC

Revocation via StatusList2021

FIDO Evidence in VCs

DID Infrastructure

Verifiable Credentials API Endpoints

MPP Agent Identity

Why Agent Passports?

How It Works

Credential Structure

Issue a Passport

Attach to MPP Requests

Verify on the Merchant Side

Trust Registry

Revocation

Error Codes

MPP Agent Identity API Endpoints

SD-JWT Selective Disclosure

Why SD-JWT?

How It Works

Creating a Presentation

SD-JWT Format

Comments (0)