Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
request()

Make a token-injected request to a provider API. The most common SDK call.

​
Signature

async request(
  method: HttpMethod | string,
  url: string,
  options?: {
    grantId?: string;
    provider?: string;
    account?: string;
    json?: unknown;
    body?: Uint8Array | string;
    extraHeaders?: Record<string, string>;
    queryParams?: Record<string, string>;
    pathParams?: Record<string, string>;
    reason?: string;
    context?: Record<string, string>;
    userToken?: string;
  },
): Promise<AlterResponse>

​
Parameters

NameTypeDescription
methodHttpMethod | stringHTTP method.
urlstringFull upstream URL.
grantIdstringExplicit grant. Mutually exclusive with provider.
providerstringResolves to a grant via userTokenGetter. Requires JWT mode.
accountstringDisambiguator when a user has multiple accounts on one provider.
jsonunknownJSON-serialized body.
bodyUint8Array | stringRaw body.
extraHeadersRecord<string, string>Additional headers (Auth header is set by the SDK).
queryParams, pathParamsRecord<string, string>Templated URL inputs.
reasonstringHuman-readable explanation, surfaces in audit logs.
contextRecord<string, string>Per-call audit metadata.
userTokenstringPer-call JWT override.

​
Returns

An AlterResponse (a standard Response with a retryInfo: RetryInfo | null property carrying retry metadata).

​
Throws

GrantNotFoundError, GrantExpiredError, GrantRevokedError, AmbiguousGrantError, NoDelegatedGrantError, PolicyViolationError, ScopeReauthRequiredError, ProviderAPIError, NetworkError. See Errors.

​
Example

const response = await vault.request(
  HttpMethod.POST,
  "https://api.openai.com/v1/chat/completions",
  {
    grantId: OPENAI_GRANT_ID,
    json: { model: "gpt-4", messages: [{ role: "user", content: "hi" }] },
    context: { tool: "summarize" },
  },
);
console.log(response.status, await response.json());

​
proxyRequest()

Forwards an HTTP exchange through the Alter backend. Use when the call must run server-side (AWS SigV4, approval-gated calls, backend rate limiting).

​
Signature

async proxyRequest(options: {
  method: HttpMethod | string;
  url: string;
  grantId: string;
  jsonBody?: unknown;
  headers?: Record<string, string>;
  queryParams?: Record<string, unknown>;
  reason?: string;
}): Promise<ApprovalResult | PendingApproval>
Auth headers (Authorization, Cookie, x-api-key, x-amz-security-token) are forbidden — the backend injects credentials at execution time.

​
Returns

  • ApprovalResult if the call ran inline. The body is base64-encoded on bodyB64 — decode with bodyText() / bodyJson() / bodyBytes().
  • PendingApproval if policy required human approval. Pass approvalId to awaitApproval(). See Approvals.

​
Example

const result = await vault.proxyRequest({
  method: HttpMethod.POST,
  url: "https://api.example.com/v1/refunds",
  grantId: GRANT_ID,
  jsonBody: { amount: 1000 },
  reason: "Customer ticket #4421",
});
boto3Client is Python-only. For AWS in Node, use proxyRequest with SigV4-typed managed secrets. See Managed Secrets → Using grants.

​
See also