Quickstart

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

const vault = new AlterVault({
  apiKey: "alter_key_...",
  caller: "my-agent",
});

const response = await vault.request(
  HttpMethod.GET,
  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  {
    grantId: "GRANT_ID",  // from Alter Connect (see below)
    queryParams: { maxResults: "10" },
  }
);

const events = await response.json();
for (const event of events.items ?? []) {
  console.log(`Event: ${event.summary}`);
}

await vault.close();

import { AlterVault, CallerType } from "@alter-ai/alter-sdk";

const vault = new AlterVault({
  apiKey: "alter_key_...",              // Required: API key from dashboard
  caller: "my-agent",                  // Optional: Caller identity for audit logs
  callerType: CallerType.AGENT,        // Optional: AGENT (default) or SERVICE
  timeout: 30000,                      // Optional: HTTP timeout in milliseconds
});

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

const vault = new AlterVault({
  apiKey: "alter_key_...",
  caller: "my-agent",
  // Called before every request — return a fresh JWT for the current user.
  // Sync or async functions are both supported.
  userTokenGetter: () => getCurrentUserJwt(),
});

// `provider` looks up the grant that belongs to the JWT's user — no grantId needed.
const response = await vault.request(
  HttpMethod.GET,
  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  { provider: "google" },
);

const authResult = await vault.authenticate();
console.log(authResult.userInfo); // { sub, email, name, ... } from the IDP

import {
  ReAuthRequiredError,
  ScopeReauthRequiredError,
  PolicyViolationError,
  TokenRefreshInProgressError,
  GrantNotFoundError,
  AmbiguousGrantError,
} from "@alter-ai/alter-sdk";

try {
  // Identity mode — the SDK resolves the grant from the configured
  // userTokenGetter. AmbiguousGrantError can only be raised on this
  // path; direct (grantId) mode addresses a single grant.
  const response = await vault.request(
    HttpMethod.GET,
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    { provider: "google" },
  );
  return await response.json();
} catch (e) {
  if (e instanceof ScopeReauthRequiredError) {
    console.log(`Scopes changed — user must re-authorize (provider: ${e.providerId}, connection: ${e.grantId})`);
  } else if (e instanceof ReAuthRequiredError) {
    console.log("User must re-authorize via Alter Connect");
  } else if (e instanceof PolicyViolationError) {
    console.log(`Access denied by policy: ${e.message} (rule: ${e.policyError})`);
  } else if (e instanceof TokenRefreshInProgressError) {
    // Another request is mid-refresh — transient, retry after backoff
    console.log(`Token refresh in progress for ${e.grantId} — retry after backoff`);
  } else if (e instanceof AmbiguousGrantError) {
    // JWT identity resolution matched multiple active grants — supply
    // `account` to disambiguate. Matching identifiers are exposed on the
    // exception so the caller can prompt or pick.
    console.log(`Multiple grants for ${e.providerId}:`, e.accountIdentifiers);
  } else if (e instanceof GrantNotFoundError) {
    console.log("User hasn't connected Google yet");
  } else {
    throw e;
  }
} finally {
  await vault.close();
}

const result = await vault.revokeGrant(grantId, {
  reason: "Agent cleanup: stale grant", // optional; stored in the audit log
});
console.log(`Revoked at ${result.revokedAt}`);

import {
  AlterVault,
  type GroupPrincipal,
  type UserPrincipal,
  type SystemPrincipal,
} from "@alter-ai/alter-sdk";

// Tie the secret to an IDP group — every member with a verified JWT gets access
const groupGrant = await vault.createManagedSecretGrant("a1b2c3d4-5e6f-7890-abcd-ef0123456789", {
  principal: {
    type: "group",
    idpId: "idp_xyz",
    externalGroupId: "okta-group-engineering",
    label: "engineering-prod-stripe",
  } satisfies GroupPrincipal,
});

// Tie the secret to a specific end user (validates userToken against the IDP).
// `label` is required so the wallet can render meaningful copy.
const userGrant = await vault.createManagedSecretGrant("a1b2c3d4-5e6f-7890-abcd-ef0123456789", {
  principal: {
    type: "user",
    userToken: currentUserJwt,
    label: "alice-prod-stripe-readonly",
  } satisfies UserPrincipal,
});

// Headless system grant — no end-user identity required. `label` is optional
// because system grants typically don't surface in the wallet.
const systemGrant = await vault.createManagedSecretGrant("a1b2c3d4-5e6f-7890-abcd-ef0123456789", {
  principal: { type: "system", label: "cron-stripe-charges" } satisfies SystemPrincipal,
});

console.log(groupGrant.grantId, groupGrant.principalType);