AI Agent Authorization Quickstart

Implement AI agent authorization with Grantex: register an agent, request consent, exchange a code, verify a JWT grant, and write audit records.

1. Install the SDK

This guide installs the current registry-verified TypeScript 0.6.0, Python 0.5.0, Go v0.3.0 (which requires Go 1.26.1+), and MCP Auth 2.0.2. See Release Status for exact package status and upgrade guidance.

TypeScript

npm install @grantex/sdk@0.6.0

2. Register your agent

TypeScript

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

3. Request authorization from a user

TypeScript

const authRequest = await grantex.authorize({
  agentId: agent.id,
  userId: 'user_abc123',
  scopes: ['calendar:read', 'payments:initiate:max_500'],
  expiresIn: '24h',
  redirectUri: 'https://yourapp.com/auth/callback',
});

// Redirect user to the consent page
console.log(authRequest.consentUrl);
// → https://consent.grantex.dev/authorize?req=eyJ...

4. Exchange the code for a grant token

After the user approves, your redirect URI receives an authorization code. Exchange it for a signed grant token:

TypeScript

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

5. Verify token signatures and claims locally

TypeScript

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']

Local verification retrieves or reuses the issuer’s JWKS and checks the token’s signature and claims. It does not prove current revocation unless the verifier performs an online state check or synchronizes revocation data.

6. Log every action

TypeScript

await grantex.audit.log({
  agentId: agent.id,
  agentDid: agent.did,
  grantId: token.grantId,
  principalId: 'user_abc123',
  action: 'payment.initiated',
  status: 'success',
  metadata: { amount: 420, currency: 'USD', merchant: 'Air India' },
});

Next steps

Core Concepts

Learn about the three primitives: agent identity, delegated grants, and audit trails.

Local Development

Run the full stack locally with Docker Compose and sandbox mode.

TypeScript SDK

Full API reference for the TypeScript SDK.

Python SDK

Full API reference for the Python SDK.

Go SDK

Full API reference for the Go SDK.

CLI

83 commands with —json support for scripting and AI agents.

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].