Quickstart

Get up and running with Grantex in under 5 minutes.

1. Install the SDK

npm

npm install @grantex/sdk

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 the token offline

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

6. Log every action

TypeScript

await grantex.audit.log({
  agentId: agent.id,
  grantId: token.grantId,
  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.

CLI

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