> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A Protocol Bridge (TypeScript)

> Inject Grantex grant tokens into Google A2A agent-to-agent communication

## Overview

The `@grantex/a2a` package bridges the [Google A2A protocol](https://github.com/google/a2a) with Grantex delegated authorization, enabling secure agent-to-agent communication with grant token authentication.

## Installation

```bash theme={null}
npm install @grantex/a2a
```

## Client — Calling A2A Agents

Send tasks to remote A2A agents with automatic grant token auth:

```typescript theme={null}
import { A2AGrantexClient } from '@grantex/a2a';

const client = new A2AGrantexClient({
  agentUrl: 'https://agent.example.com/a2a',
  grantToken: 'eyJ...', // Grantex grant token
});

// Send a task
const task = await client.sendTask({
  message: { role: 'user', parts: [{ type: 'text', text: 'Search for flights' }] },
});

// Check status
const status = await client.getTask({ id: task.id });

// Cancel
await client.cancelTask({ id: task.id });
```

The TypeScript client's synchronous token parsing is an unverified convenience
check only. It must never be used as the remote authorization boundary. The A2A
server must run the JWKS-backed middleware below before accepting or executing
the JSON-RPC request.

## Server Middleware — Validating Incoming Tokens

Validate Grantex grant tokens on incoming A2A requests:

```typescript theme={null}
import { createA2AAuthMiddleware } from '@grantex/a2a';

const authMiddleware = createA2AAuthMiddleware({
  jwksUri: 'https://grantex.dev/.well-known/jwks.json',
  requiredScopes: ['read', 'write'],
});

// In your A2A handler:
const grant = await authMiddleware(request);
console.log(grant.principalId, grant.scopes);
```

## Agent Card Builder

Generate A2A-compliant agent cards with Grantex auth configuration:

```typescript theme={null}
import { buildGrantexAgentCard } from '@grantex/a2a';

const card = buildGrantexAgentCard({
  name: 'Travel Agent',
  description: 'Books flights and hotels',
  url: 'https://travel-agent.example.com/a2a',
  jwksUri: 'https://grantex.dev/.well-known/jwks.json',
  issuer: 'https://grantex.dev',
  requiredScopes: ['travel:read', 'travel:write'],
  delegationAllowed: true,
});
```

## JWT Utilities

Decode grant tokens offline (without verification):

```typescript theme={null}
import { decodeJwtPayload, isTokenExpired } from '@grantex/a2a';

const payload = decodeJwtPayload(grantToken);
console.log(payload.sub, payload.scp, payload.bdg);

if (isTokenExpired(payload)) {
  // Token needs refresh
}
```

Decoded payloads are untrusted display/debug data until separately verified.
Do not make an authorization, routing, billing, or audit-attribution decision
from `decodeJwtPayload()` output.

## Ownership

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

## Current Authority and Human Identity

Use the exact integration version and minimum primary SDK in [Release Status](/release-status).
Per-invocation issuer authority and trusted principal/agent binding are opt-in.
Configure the callback with the trusted issuer and derive identity from the host's
authenticated session; signature and scope checks alone do not prove current
revocation or human consent. See [SDK execution authority](/guides/sdk-execution-authority)
for configuration, denial behavior and manifest/decision/caps boundaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.