Authentication

Steward provides a complete authentication system for apps built on the platform. Users authenticate once and get a wallet, session, and identity that works across multiple Steward-powered apps.

Auth Methods

Passkeys (WebAuthn)

Phishing-resistant, passwordless login using biometrics or hardware keys.

Email Magic Link

One-click sign-in via a link sent to the user’s email.

OAuth Providers

Google, Discord, and Twitter/X via PKCE popup flow.

SIWE

Sign-In With Ethereum for users who already have a wallet.

How It Works

The auth flow follows a standard pattern regardless of the sign-in method:

User → Your App → Steward API → JWT + Wallet

The user initiates sign-in (passkey, email, OAuth, or SIWE)
Steward verifies the credential and creates or retrieves the user
Steward returns a JWT access token (15 min) and a refresh token (30 days)
Your app uses the access token for API calls via StewardClient

Session Management

Steward uses a two-token session model:

Token	Lifetime	Purpose
Access token (JWT)	15 minutes	Authenticates API requests via `Authorization: Bearer` header
Refresh token	30 days	Exchanges for a new access token when the current one expires

The SDK handles token refresh automatically. When the access token is within 2 minutes of expiry, auth.getToken() triggers a background refresh.

import { StewardAuth } from "@stwd/sdk";

const auth = new StewardAuth({
  baseUrl: "http://localhost:3200",
  storage: localStorage, // persist across page reloads
  onSessionChange: (session) => {
    console.log(session ? "Signed in" : "Signed out");
  },
});

// Check session state
auth.isAuthenticated();  // boolean
auth.getSession();       // StewardSession | null
auth.getToken();         // string | null (auto-refreshes)

// Sign out
auth.signOut();          // clears local tokens
auth.revokeSession();    // clears local + revokes refresh token on server

Provider Discovery

Your app can query the server to discover which auth methods are enabled:

const providers = await auth.getProviders();
// {
//   passkey: true,
//   email: true,
//   siwe: true,
//   google: true,
//   discord: true,
//   oauth: ["google", "discord"]
// }

The <StewardLogin> React component does this automatically and only shows buttons for enabled methods.

Cross-Tenant Identity

Steward supports multi-tenant authentication. A single user identity (email, wallet) can belong to multiple apps (tenants). Each tenant is an isolated environment with its own agents, policies, and configuration. See Cross-Tenant Identity for details on tenant management, join modes, and switching between apps.

SDK vs React

SDK (any JS runtime)
React

import { StewardAuth } from "@stwd/sdk";

const auth = new StewardAuth({ baseUrl: "http://localhost:3200" });
const result = await auth.signInWithPasskey("user@example.com");

const client = new StewardClient({
  baseUrl: "http://localhost:3200",
  bearerToken: auth.getToken(),
});

import { StewardProvider, StewardLogin, StewardAuthGuard } from "@stwd/react";

function App() {
  return (
    <StewardProvider
      client={client}
      agentId="my-agent"
      auth={{ baseUrl: "http://localhost:3200" }}
    >
      <StewardAuthGuard>
        <Dashboard />
      </StewardAuthGuard>
    </StewardProvider>
  );
}

API Keys, Agent Tokens, and Platform Keys

Steward uses separate credentials for different audiences:

Credential	Header	Scope	Notes
Tenant API key	`X-Steward-Key` plus optional `X-Steward-Tenant`	Tenant API operations	Platform tenant creation returns the raw key once. Steward stores only the hash.
Agent JWT	`Authorization: Bearer <token>`	One agent within one tenant	Created by platform agent-token endpoints and carries `scope: "agent"`.
User/session JWT	`Authorization: Bearer <token>`	Authenticated user/session	Returned by passkey, email, OAuth, and SIWE flows.
Platform key	`X-Steward-Platform-Key`	Cross-tenant `/platform/*` administration	Configured out of band in `STEWARD_PLATFORM_KEYS`.

Production deployments should set a JWT secret separate from STEWARD_MASTER_PASSWORD. The current code is being unified around JWT env naming; check the deployment guide before configuring production secrets.

Passkeys — WebAuthn setup and usage
Email — Magic link configuration
OAuth — Google, Discord, Twitter/X setup
Cross-Tenant Identity — Multi-app user management
React Components — Drop-in UI components

Get Started

Authentication

Concepts

Guides

Authentication Overview

Authentication

Auth Methods

Passkeys (WebAuthn)

Email Magic Link

OAuth Providers

SIWE

How It Works

Session Management

Provider Discovery

Cross-Tenant Identity

SDK vs React

API Keys, Agent Tokens, and Platform Keys

​Authentication

​Auth Methods

Passkeys (WebAuthn)

Email Magic Link

OAuth Providers

SIWE

​How It Works

​Session Management

​Provider Discovery

​Cross-Tenant Identity

​SDK vs React

​API Keys, Agent Tokens, and Platform Keys

​Related

Authentication

Auth Methods

How It Works

Session Management

Provider Discovery

Cross-Tenant Identity

SDK vs React

API Keys, Agent Tokens, and Platform Keys

Related