Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.steward.fi/llms.txt

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

​
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
  1. The user initiates sign-in (passkey, email, OAuth, or SIWE)
  2. Steward verifies the credential and creates or retrieves the user
  3. Steward returns a JWT access token (15 min) and a refresh token (30 days)
  4. Your app uses the access token for API calls via StewardClient

​
Session Management

Steward uses a two-token session model:
TokenLifetimePurpose
Access token (JWT)15 minutesAuthenticates API requests via Authorization: Bearer header
Refresh token30 daysExchanges 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: "https://api.steward.fi",
  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

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

const auth = new StewardAuth({ baseUrl: "https://api.steward.fi" });
const result = await auth.signInWithPasskey("user@example.com");

const client = new StewardClient({
  baseUrl: "https://api.steward.fi",
  bearerToken: auth.getToken(),
});

​
API Keys, Agent Tokens, and Platform Keys

Steward uses separate credentials for different audiences:
CredentialHeaderScopeNotes
Tenant API keyX-Steward-Key plus optional X-Steward-TenantTenant API operationsPlatform tenant creation returns the raw key once. Steward stores only the hash.
Agent JWTAuthorization: Bearer <token>One agent within one tenantCreated by platform agent-token endpoints and carries scope: "agent".
User/session JWTAuthorization: Bearer <token>Authenticated user/sessionReturned by passkey, email, OAuth, and SIWE flows.
Platform keyX-Steward-Platform-KeyCross-tenant /platform/* administrationConfigured 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.