Skip to main content

​
1. Install the SDK

npm install @grantex/sdk

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

​
3. Request authorization from a user

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

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

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.