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

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.