> ## 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 Overview

> How authentication works in Steward: methods, sessions, and cross-tenant identity.

# 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

<CardGroup cols={2}>
  <Card title="Passkeys (WebAuthn)" icon="fingerprint" href="/auth/passkeys">
    Phishing-resistant, passwordless login using biometrics or hardware keys.
  </Card>

  <Card title="Email Magic Link" icon="envelope" href="/auth/email">
    One-click sign-in via a link sent to the user's email.
  </Card>

  <Card title="OAuth Providers" icon="right-to-bracket" href="/auth/oauth">
    Google, Discord, and Twitter/X via PKCE popup flow.
  </Card>

  <Card title="SIWE" icon="ethereum" href="/auth/cross-tenant">
    Sign-In With Ethereum for users who already have a wallet.
  </Card>
</CardGroup>

## 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:

| 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.

```typescript theme={null}
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:

```typescript theme={null}
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](/auth/cross-tenant) for details on tenant management, join modes, and switching between apps.

## SDK vs React

<Tabs>
  <Tab title="SDK (any JS runtime)">
    ```typescript theme={null}
    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(),
    });
    ```
  </Tab>

  <Tab title="React">
    ```tsx theme={null}
    import { StewardProvider, StewardLogin, StewardAuthGuard } from "@stwd/react";

    function App() {
      return (
        <StewardProvider
          client={client}
          agentId="my-agent"
          auth={{ baseUrl: "https://api.steward.fi" }}
        >
          <StewardAuthGuard>
            <Dashboard />
          </StewardAuthGuard>
        </StewardProvider>
      );
    }
    ```
  </Tab>
</Tabs>

## 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.

## Related

* [Passkeys](/auth/passkeys) — WebAuthn setup and usage
* [Email](/auth/email) — Magic link configuration
* [OAuth](/auth/oauth) — Google, Discord, Twitter/X setup
* [Cross-Tenant Identity](/auth/cross-tenant) — Multi-app user management
* [React Components](/sdk/react-components) — Drop-in UI components