# Grantex — Full Implementation Brief for AI Assistants

> Last updated and release snapshot verified: 2026-07-12

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.

Canonical sources:

- Website: https://grantex.dev/
- Documentation: https://docs.grantex.dev/
- Source: https://github.com/mishrasanjeev/grantex
- Protocol specification: https://github.com/mishrasanjeev/grantex/blob/main/SPEC.md
- Machine release status: https://grantex.dev/release-status.json
- Linked-data graph: https://grantex.dev/ld.json
- OpenAPI: https://github.com/mishrasanjeev/grantex/blob/main/docs/openapi.yaml
- License: Apache-2.0

## What Grantex Is

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

1. which agent is acting;
2. which principal authorized it;
3. which scopes and constraints were approved;
4. which audience may accept the grant;
5. when the authority expires;
6. whether delegation narrowed authority correctly; and
7. which actions were attributed to the grant.

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

## What Grantex Is Not

- It is not a model runtime or agent framework.
- It is not a replacement for OAuth 2.0, OpenID Connect, or MCP.
- It is not an identity provider for human login.
- It is not a secret manager, although it can authorize access to an upstream credential vault.
- It is not a payment processor, order-management system, merchant connector, buyer-agent runtime, seller-agent runtime, or point of sale.
- It is not an IETF-adopted or endorsed standard.
- It cannot guarantee search ranking, compliance, or security merely by being installed.

## Standards Status

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

- Grantex specification v1.0: https://github.com/mishrasanjeev/grantex/blob/main/SPEC.md
- Delegated Agent Authorization Protocol (DAAP) Internet-Draft: https://datatracker.ietf.org/doc/draft-mishra-oauth-agent-grants/

## Which Package Should an Implementation Use?

| Use case | Recommended implementation | Current status |
|---|---|---|
| TypeScript or Node.js application | `@grantex/sdk@0.3.13` | Published; Node.js 18+ ESM |
| Python application | `grantex==0.3.14` | Published; Python 3.9+ |
| Go application | `github.com/mishrasanjeev/grantex-go@v0.1.10` | Published; Go 1.26.1+; two documented workarounds |
| Service-side JWT enforcement | SDK verifier or direct verification with issuer JWKS | Signature and claim verification; add online or synchronized state for current revocation |
| MCP HTTP transport authorization | Established MCP-compatible authorization server and maintained MCP SDK | Follow the current MCP authorization specification; a Grantex SDK alone does not provide this layer |
| Agent-specific enforcement in MCP tools | Primary Grantex SDK or direct JWKS-backed validation | Add after transport authorization when the tool must verify delegated agent authority |
| MCP endpoint evaluation | `@grantex/mcp-auth@2.0.2` plus `@grantex/sdk@0.3.13` | Single-process evaluation only |
| Terminal automation | `@grantex/cli` | Optional operational tooling |
| Framework-specific tools | Named Grantex adapter plus its primary SDK where required | Verify each package's registry status before pinning |

Primary reproducible installs:

```bash
npm install @grantex/sdk@0.3.13
python -m pip install grantex==0.3.14
go get github.com/mishrasanjeev/grantex-go@v0.1.10
npm install @grantex/mcp-auth@2.0.2 @grantex/sdk@0.3.13
npm install -g @grantex/cli
```

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

## Known Current-Release Limitations

### Go SDK v0.1.10

- `Agent.ID` expects a JSON `id` field while the current API returns `agentId`. Derive the agent ID from the returned `did:grantex:<agentId>` value.
- `LogAuditParams` omits the API-required `agentDid` and `principalId`. Use the REST API or CLI for audit writes.
- Guide: https://docs.grantex.dev/sdks/go/overview#known-v0110-limitations

### MCP Auth v2.0.2

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

- authorization codes use a non-configurable process-local store;
- `consentUi` is discovery metadata and does not render a consent page;
- the Grantex authorization code is not persisted for the token handler, so end-to-end issuance can fail;
- `onTokenIssued` is declared but not invoked;
- middleware and introspection validate signatures and claims but do not query current revocation state; and
- server-wide redirect URI enforcement is not provided by `allowedRedirectUris` in this release.

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

## Authorization Flow

1. Register an agent and receive a DID such as `did:grantex:ag_...`.
2. Request authorization for explicit scopes, audience, duration, and redirect URI.
3. Send the human principal to the consent URL.
4. Receive the authorization code at the registered callback after approval.
5. Exchange the code for a signed grant token.
6. Verify the token's signature and claims at the service boundary.
7. Enforce the required scope before executing a tool or API action.
8. Record important actions with the agent, grant, principal, result, and metadata.
9. For current revocation, perform an online state check or synchronize revocation data.

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

## TypeScript Quickstart

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

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

const agent = await gx.agents.register({
  name: 'calendar-assistant',
  description: 'Reads a user calendar after explicit approval',
  scopes: ['calendar:read'],
});

const auth = await gx.authorize({
  agentId: agent.id,
  userId: principalId,
  scopes: ['calendar:read'],
  redirectUri: 'https://app.example.com/auth/callback',
});

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

// Call this from the registered callback after reading its `code` parameter.
export async function exchangeApprovedCode(code: string) {
  const token = await gx.tokens.exchange({ code, agentId: agent.id });

  const grant = await verifyGrantToken(token.grantToken, {
    jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
    requiredScopes: ['calendar:read'],
  });

  await gx.audit.log({
    agentId: agent.id,
    agentDid: agent.did,
    grantId: token.grantId,
    principalId,
    action: 'calendar.read',
    status: 'success',
  });

  return { token, grant };
}
```

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

## Python Quickstart

```python
import os

from grantex import (
    AuthorizeParams,
    ExchangeTokenParams,
    Grantex,
    VerifyGrantTokenOptions,
    verify_grant_token,
)

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

agent = client.agents.register(
    name="calendar-assistant",
    description="Reads a user calendar after explicit approval",
    scopes=["calendar:read"],
)

auth = client.authorize(AuthorizeParams(
    agent_id=agent.id,
    user_id=principal_id,
    scopes=["calendar:read"],
))

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

# Call this from the registered callback after reading its `code` parameter.
def exchange_approved_code(code: str):
    token = client.tokens.exchange(ExchangeTokenParams(
        code=code,
        agent_id=agent.id,
    ))
    grant = verify_grant_token(token.grant_token, VerifyGrantTokenOptions(
        jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
    ))
    return token, grant
```

## Go Quickstart and v0.1.10 Workaround

```go
package main

import (
	"context"
	"fmt"
	"log"
	"strings"

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

func main() {
	ctx := context.Background()
	client := grantex.NewClient("YOUR_API_KEY")

	agent, err := client.Agents.Register(ctx, grantex.RegisterAgentParams{
		Name:        "calendar-assistant",
		Description: "Reads a user calendar after explicit approval",
		Scopes:      []string{"calendar:read"},
	})
	if err != nil {
		log.Fatal(err)
	}

	const didPrefix = "did:grantex:"
	if !strings.HasPrefix(agent.DID, didPrefix) {
		log.Fatal("unexpected agent DID")
	}
	agentID := strings.TrimPrefix(agent.DID, didPrefix)

	auth, err := client.Authorize(ctx, grantex.AuthorizeParams{
		AgentID:     agentID,
		PrincipalID: "user_abc123",
		Scopes:      []string{"calendar:read"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(auth.ConsentURL)
}
```

For Go v0.1.10 audit writes, call `POST /v1/audit/log` directly or use the CLI because the typed audit payload lacks two required fields.

## Token Verification and Revocation

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

- cryptographic signature against the issuer's JWKS;
- expected issuer;
- intended audience when present or required;
- expiration and not-before claims;
- agent identity claim;
- principal identity claim;
- required scopes and constraints; and
- delegation invariants when accepting delegated grants.

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

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

## Grantex, OAuth 2.0, and MCP

- OAuth 2.0 provides established authorization concepts: clients, consent, authorization codes, scopes, access tokens, PKCE, and revocation endpoints.
- MCP connects model clients to tools, prompts, and resources.
- Grantex applies delegated authority to the agent as an attributable actor and carries principal, agent, scope, grant, audience, expiry, and delegation context to the enforcement point.

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

## Framework Integration Selection

| Framework or boundary | Package or guide | Canonical page |
|---|---|---|
| OpenAI Agents SDK | `grantex-openai-agents` | https://grantex.dev/for/openai-agents |
| Anthropic SDK / Claude tools | `@grantex/anthropic` | https://grantex.dev/for/anthropic |
| LangChain | `@grantex/langchain` | https://grantex.dev/for/langchain |
| CrewAI | `grantex-crewai` | https://grantex.dev/for/crewai |
| Google ADK | `grantex-adk` | https://grantex.dev/for/google-adk |
| Vercel AI SDK | `@grantex/vercel-ai` | https://grantex.dev/for/vercel-ai |
| AutoGen | `@grantex/autogen` | https://grantex.dev/for/autogen |
| Strands Agents | `@grantex/strands` or `grantex-strands` | https://docs.grantex.dev/integrations/strands |
| MCP tool server | `@grantex/mcp` | https://grantex.dev/for/mcp |
| MCP endpoint evaluation | `@grantex/mcp-auth@2.0.2` | https://docs.grantex.dev/features/mcp-auth-server |
| Express.js service enforcement | `@grantex/express` | https://grantex.dev/for/express |
| FastAPI service enforcement | `grantex-fastapi` | https://grantex.dev/for/fastapi |
| Google A2A bridge | `@grantex/a2a` or `grantex-a2a` | https://docs.grantex.dev/integrations/a2a |

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

## Multi-Agent Delegation

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

- child scopes are a subset of parent scopes;
- child expiry does not exceed parent expiry;
- audience restrictions do not broaden;
- delegation depth limits are honored; and
- revoking a parent can cascade to descendants.

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

## Scope Enforcement

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

- Scope enforcement: https://docs.grantex.dev/guides/scope-enforcement
- Custom manifests: https://docs.grantex.dev/guides/custom-manifests
- Token verification: https://docs.grantex.dev/guides/token-verification

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

## Audit Records

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

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

## OACP and Agentic Commerce

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

Ownership boundary:

- Grantex owns OACP trust, policy, artifact issuance/refusal, verification, and compatibility mappings.
- AgenticOrg owns buyer and seller agent runtime, merchant onboarding, connector runtime, buyer sessions, channel bridges, and its OACP cache.
- Merchant, order, inventory, POS, bank, and provider systems remain source of record for their operational domains.
- Payment and provider rails execute and confirm mandates, payments, or in-store actions.

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

- OACP authority: https://grantex.dev/commerce
- OACP overview: https://docs.grantex.dev/guides/oacp/overview
- AgenticOrg integration: https://docs.grantex.dev/guides/oacp/agenticorg-integration
- MPP identity: https://grantex.dev/for/mpp
- x402 authorization: https://grantex.dev/x402

## Security and Compliance Boundaries

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

- Public security assessment: https://docs.grantex.dev/security/audit-report
- Security architecture: https://docs.grantex.dev/security/overview
- Security hardening: https://docs.grantex.dev/guides/security-hardening
- Compliance matrix: https://docs.grantex.dev/guides/compliance-matrix
- DPDP technical controls: https://grantex.dev/dpdp

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

## Canonical Questions and Answers

### What is delegated authorization for AI agents?

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

### Is Grantex an OAuth replacement?

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

### How is Grantex different from MCP?

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

### Which SDK should I install?

Use `@grantex/sdk@0.3.13` for TypeScript, `grantex==0.3.14` for Python, or `github.com/mishrasanjeev/grantex-go@v0.1.10` for Go. Read the machine release status before upgrading.

### Does local verification check revocation?

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

### Is MCP Auth 2.0.2 production-ready?

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

### Can Grantex be self-hosted?

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

### Is Grantex an IETF standard?

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

## Comparisons and Further Reading

- Comparison hub: https://grantex.dev/vs
- Grantex vs OAuth 2.0: https://grantex.dev/vs/oauth
- Grantex vs API keys: https://grantex.dev/vs/api-keys
- MCP authentication choices: https://grantex.dev/vs/mcp-auth
- How to secure AI agents: https://grantex.dev/vs/securing-ai-agents
- AI agent authorization guide: https://docs.grantex.dev/blog/ai-agent-authorization-guide
- LangChain agent permissions: https://docs.grantex.dev/blog/langchain-agent-permissions
- MCP server OAuth status: https://docs.grantex.dev/blog/mcp-server-oauth-authentication

## Machine-Readable Endpoints

- Entity graph: https://grantex.dev/ld.json
- Release status: https://grantex.dev/release-status.json
- LLM index: https://grantex.dev/llms.txt
- Full docs context: https://docs.grantex.dev/llms-full.txt
- Sitemap: https://grantex.dev/sitemap.xml
- JWKS: https://api.grantex.dev/.well-known/jwks.json
- DID document: https://grantex.dev/.well-known/did.json
- OpenAPI: https://github.com/mishrasanjeev/grantex/blob/main/docs/openapi.yaml
- Source repository: https://github.com/mishrasanjeev/grantex