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";

Running the examples

The TypeScript examples in these docs use top-level await, which Node only allows in an ES module. To run one as a standalone script, save it with the .mts extension and run it with tsx:

npm install --save-dev tsx
npx tsx example.mts

A plain .ts file in a project without "type": "module" is compiled as CommonJS and fails with Top-level await is currently not supported with the "cjs" output format. Inside an existing ESM project, or inside an async function, the examples work as written.

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 the agent’s own key (from agents.create; issued today with the legacy alter_key_… prefix). 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.