TypeScript SDK

Install, configure, and get started with the @grantex/sdk TypeScript SDK.

Installation

npm install @grantex/sdk

Requirements

• Node.js 18+ (uses native fetch and crypto)
• ESM only — the package ships as "type": "module" with TypeScript NodeNext resolution

Configuration

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({
  apiKey: process.env.GRANTEX_API_KEY,  // required (or set GRANTEX_API_KEY env var)
  baseUrl: 'https://api.grantex.dev',   // optional, defaults to production
  timeout: 30_000,                       // optional, request timeout in ms
});

Options

apiKey · string · required

Your Grantex API key. Falls back to the GRANTEX_API_KEY environment variable if omitted.

baseUrl · string · default: "https://api.grantex.dev"

Base URL for the Grantex API. Override for self-hosted or local development.

timeout · number · default: "30000"

Request timeout in milliseconds. The SDK uses AbortController to enforce the deadline.

Quick start

The complete authorization flow in one script:

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

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// 1. Register an agent
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...

// 2. Request user authorization
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 the user to authRequest.consentUrl

// 3. Exchange the authorization code for a grant token
const token = await grantex.tokens.exchange({
  code,                  // from the redirect callback
  agentId: agent.id,
});
console.log(token.grantToken);  // RS256 JWT
console.log(token.scopes);      // ['calendar:read', 'payments:initiate:max_500']

// 4. Verify the token offline (no Grantex dependency at runtime)
const grant = await verifyGrantToken(token.grantToken, {
  jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  requiredScopes: ['calendar:read'],
});
console.log(grant.principalId); // 'user_abc123'

// 5. Revoke the token when done
await grantex.tokens.revoke(grant.tokenId);

Available resources

The Grantex client exposes the following sub-clients:

Property	Description	Reference
grantex.agents	Register, list, update, and delete agents	Agents
grantex.tokens	Exchange, verify, and revoke tokens	Tokens
grantex.grants	Manage grants, delegate to sub-agents	Grants
grantex.audit	Log and query the tamper-evident audit trail	Audit
grantex.webhooks	Create and manage webhook endpoints	Webhooks
grantex.policies	Define authorization policies	Policies
grantex.compliance	Compliance summaries, exports, evidence packs	Compliance
grantex.anomalies	Detect and acknowledge anomalies	Anomalies
grantex.billing	Subscription management via Stripe	Billing
grantex.scim	SCIM 2.0 user provisioning	SCIM
grantex.sso	OIDC single sign-on	SSO
grantex.principalSessions	End-user dashboard sessions	Principal Sessions
grantex.vault	Store, retrieve, and exchange service credentials	Vault
grantex.budgets	Per-grant spending budgets and transactions	Budgets
grantex.events	SSE event streaming	Events
grantex.usage	Usage metering and history	Usage
grantex.domains	Custom domain verification	Domains
grantex.webauthn	FIDO2/WebAuthn passkey management	WebAuthn
grantex.credentials	Verifiable Credentials and SD-JWT	Credentials
grantex.passports	MPP agent passport credentials	Passports
grantex.dpdp	DPDP Act 2023 compliance — consent, grievances, erasure, exports	DPDP

Standalone exports

These functions can be used without instantiating a Grantex client:

Export	Description	Reference
verifyGrantToken()	Offline JWT verification via JWKS	Offline Verification
generatePkce()	Generate PKCE S256 challenge pairs	PKCE
verifyWebhookSignature()	Verify webhook payload signatures	Webhooks

Error handling

All errors extend GrantexError. See the Error Handling reference for the full hierarchy and usage patterns.