Accounts and authentication

Stead has two account types. A developer account owns projects and manages deployments, keys, and approvals. A customer account belongs to one project’s application. The same email can have both accounts, with separate passwords and sessions.

Developer login

Register and verify your email at app.getstead.dev. The console uses a secure, HttpOnly, host-scoped session cookie. Sign in separately in each browser you use.

npx --yes getstead@0.2.1 login --api-url https://api.getstead.dev

The CLI prints a console link and a confirmation code. Open the link, check that the code matches, and authorize your terminal. The terminal receives its own session, saved with private file permissions and associated with the API URL. It does not copy the browser’s cookie. getstead logout revokes and removes the saved terminal session.

Password reset is available on the console’s sign-in page. It revokes existing developer sessions, including CLI sessions; run getstead login again afterward.

Built-in customer login

Use SteadAuth with the project ID shown in the console. The project ID and API URL are public configuration.

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

export function connectCustomer(projectId: string) {
  const auth = new SteadAuth({
    url: 'https://api.getstead.dev',
    projectId,
  });
  const client = new SteadClient({
    url: 'https://api.getstead.dev',
    token: auth.getToken,
  });
  return { auth, client };
}

From your browser’s signup form:

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

export async function register(
  auth: SteadAuth,
  name: string,
  email: string,
  password: string,
) {
  await auth.signUp({ name, email, password, callbackURL: location.origin });
}

Open the email verification link, return to your app, and call auth.signIn({ email, password }). The SDK receives a signed customer session through the set-auth-token response header. auth.getToken() exchanges it for a short-lived customer token and refreshes that token when needed.

The SDK uses bearer headers with credentials: 'omit'; it does not depend on third-party cookies. Customer tokens identify a project and customer. They do not authorize project management or approvals.

Browser origins and callbacks

Save each allowed origin in the project’s console settings before testing authentication. For the starter, use http://localhost:5173. http://127.0.0.1:5173 and a different port are different origins. Production origins must use HTTPS; loopback development may use HTTP. Wildcards and URLs with paths are not accepted.

Use a callback or reset URL on one of those registered origins. Register the customer application’s origin, even if you are already signed into the developer console. The console’s own origin does not automatically grant customer access to your project.

Persistence and logout

By default, SteadAuth keeps its session in memory. For persistence, pass a previously saved sessionToken and implement onSessionToken. The callback receives undefined when the SDK clears the session. A signed session is a secret: choose storage according to your application’s XSS threat model. The starter demonstrates session storage scoped to its browser tab.

Call auth.signOut() to clear the local session and request server revocation. A previously minted short-lived token can remain valid until expiry. Clear customer UI state and remount your React chat when the identity changes so one person’s messages cannot remain visible to the next person.

Password reset uses requestPasswordReset(email, redirectTo), followed by resetPassword(token, newPassword) on the callback page. Never log the token or include a full reset/verification URL in a bug report.

The hosted beta supports email/password authentication. For an existing identity provider, use server-side token exchange.