Integrate an existing app

Your application supplies its UI and customer identity. Stead runs the agent program you deploy, records its progress, and serves the data you explicitly expose.

Choose an authentication path

Use built-in customer authentication if you need email and password signup. If your application already authenticates customers, exchange your server’s verified user ID for a short-lived Stead token.

In both cases, your frontend receives only customer authority. Keep project credentials and provider keys on the server or in the developer console.

Install the SDK

npm install @getstead/client@0.2.0
# For React applications:
npm install @getstead/react@0.2.0

Set your project’s exact frontend origin in Settings → Browser origins in the console. An origin includes the scheme, hostname, and port, without a path. Register local development and production separately.

Reuse your application’s login

This function belongs in your trusted backend. Call it only after your existing authentication middleware has verified the request, using the user ID from that middleware.

import { SteadClient } from '@getstead/client';

const admin = new SteadClient({
  url: 'https://api.getstead.dev',
  token: process.env.STEAD_PROJECT_SECRET!,
});

export async function tokenForVerifiedUser(verifiedUserId: string) {
  const { token, expiresAt } = await admin.exchangeToken(verifiedUserId);
  return { token, expiresAt };
}

The exchange creates or reuses the customer identified by externalId within your project. Do not accept an arbitrary user ID from the request body: whoever selects that ID selects the Stead identity. Your backend must authorize it. Protect this route using your application’s session and CSRF controls, and prevent caching of its response.

Provide a token callback to the browser client so it can obtain a fresh token when making a request or reconnecting a stream. Your callback should cache tokens until shortly before expiresAt, coalesce simultaneous refreshes, and clear the cache when your user signs out.

import { SteadClient } from '@getstead/client';

export function customerClient(getFreshToken: () => Promise<string>) {
  return new SteadClient({
    url: 'https://api.getstead.dev',
    token: getFreshToken,
  });
}

Revoking a project credential prevents new exchanges with that credential. An already issued customer token remains valid until its expiry. Your application owns logout and revocation behavior for its own sessions.

Run the deployed agent

After deploying the starter, a customer client can run its support agent:

import type { SteadClient } from '@getstead/client';

export async function ask(client: SteadClient, input: string) {
  const { run } = await client.startRun({
    agent: 'support-agent',
    input,
    async: true,
  });
  const stream = client.streamRun(run.id);
  for await (const item of stream) {
    if (item.kind === 'model-delta') process.stdout.write(item.text);
  }
  return stream.state.runStatus;
}

The example is a Node consumer of a customer client. In a browser, update your UI instead of process.stdout. For React, use useAgent.

Customer requests name an agent and input. They cannot replace the deployed steps, tool permissions, budget, or customer identity. Enable endUserRuns on each agent intended for customer access; an undeployed or unavailable agent returns 404.

Read application data

client.select('orders', { limit: 25 }) returns { rows, rowCount } through the project’s exposures and SQL policies. Customer data access is select-only; writes happen through deployed tools. See SQL and data access before exposing a table.

Built-in authentication identities and externally exchanged identities are separate namespaces. Switching authentication systems does not automatically merge their data or conversations.