TypeScript SDK

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

This is the server-side SDK (Node, Bun, Deno, edge runtimes with fetch). It is not for browser code — 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 background tasks drain and HTTP/2 connections release.

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(), AWS SigV4 bridge, scopes.list() — every credential-injection path.

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.

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! });

Conventions

• Every method is async and returns a Promise. Use await.
• Models are frozen objects. 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.