TypeScript SDK

The TypeScript SDK ships as the @alter-ai/alter-sdk package on npm. Node.js 20+.

This is a server-side Node.js SDK. It uses Node-only APIs and is not supported in browsers, Bun, Deno, or edge runtimes. For the browser-side OAuth widget that opens the consent popup, see the Connect SDK.

npm install @alter-ai/alter-sdk

import { App, Agent, HttpMethod } from "@alter-ai/alter-sdk";

Two clients

The SDK exposes two top-level clients. They share the request surface but differ in principal and identity scoping.

App

Construct with an alter_rk_… key. Acts as the application — provisions agents, mints Connect sessions, manages grants, and proxies provider calls under stored grants.

Agent

Construct with an alter_ak_… key. Workload-scoped: can only reach credentials delegated or directly bound to the agent. The right entry point for AI agents and tool-calling workloads.

Both classes are async. Always close them via await app.close() (or wrap usage in try/finally) so pending work completes and the client rejects subsequent use deterministically.

const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const page = await app.listGrants();
} finally {
  await app.close();
}

Reference

Client

App and Agent constructors, lifecycle, withConstraints, getAgent.

Calling APIs

request(), proxyRequest(), scopes.list(), and spans.emit().

Connect & Grants

Connect sessions, grant CRUD, delegation revoke, managed-secret grants, HITL approvals.

Agents & Keys

app.agents.* CRUD, Agent.me / trace / withConstraints, keys.derive / rotate / revoke.

Types

Models returned across the SDK surface.

Errors

Typed exception hierarchy.

Provider discovery

providerSpecs.list / get / listOperations / getOperation.

Express

AsyncLocalStorage + userTokenGetter pattern for per-request identity.

Next.js

Server Actions and Route Handlers with the App Router.

Configuration

The constructor accepts an apiKey argument; application code is responsible for sourcing it. The convention is to read it from the process environment:

Variable	Used by	Description
ALTER_API_KEY	application code (typical app workload)	Conventional name when the application owns one app-level key.
AGENT_API_KEY	application code (agent workload)	Conventional name when the workload runs as a managed agent.

For agent workloads, the convention is to read AGENT_API_KEY in application code:

import { Agent } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: process.env.AGENT_API_KEY! });
try {
  const info = await agent.me();
  console.log(info.status);
} finally {
  await agent.close();
}

Conventions

• I/O and lifecycle methods are asynchronous and return a Promise. Use await.
• Model class instances are frozen. Field names are camelCase (the wire format is snake_case; the SDK maps automatically).
• Methods that retrieve tokens never return the token plaintext. The SDK injects it into the outbound request.
• Public exceptions extend AlterSDKError. See Errors.
• Time-budget parameters are in milliseconds (matches setTimeout, Date.now()). User-selectable durations passed to the Connect UI are in seconds.