Shoo

https://docs.shoo.dev/docs
Admin
Shoo is a minimal auth broker that simplifies Google sign-in by handling OAuth + PKCE to provide a...
Tokens:22,633
Snippets:207
Trust Score:4.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Shoo packages

Source: https://docs.shoo.dev/docs/getting-started

Install the Shoo React and auth packages. Run this in your Next.js project root.

```bash
npm install @shoojs/react @shoojs/auth
```

--------------------------------

### Install @shoojs/react

Source: https://docs.shoo.dev/docs/convex

Install the Shoo React package to enable Shoo authentication in your Convex app.

```bash
npm install @shoojs/react
```

--------------------------------

### auth.startSignIn(params?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Starts the sign-in flow, optionally with parameters. This initiates the authentication process.

```APIDOC
## auth.startSignIn(params?)

### Description
Starts the sign-in flow. This initiates the authentication process.

### Method
CREATE

### Endpoint
auth.startSignIn(params?)

### Parameters
#### Parameters
- **params** (StartSignInOptions) - Optional - The sign-in options.

### Response
#### Success Response (200)
- **void** - No return value.

### Response Example
```json
{}
```

--------------------------------

### Install @shoojs/auth

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Installs the @shoojs/auth package, which provides a browser client and server verifier for Shoo.

```bash
npm install @shoojs/auth
```

--------------------------------

### auth.startSignIn() examples

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Saves a sign-in transaction in sessionStorage and navigates to Shoo. The first call uses defaults; the second requests profile data and returns to /settings. Rejects without navigating if storage is not writable.

```javascript
await auth.startSignIn();
await auth.startSignIn({ requestPii: true, returnTo: "/settings" });
```

--------------------------------

### auth.startSessionMonitor(options?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Starts monitoring the session for changes.

```APIDOC
## auth.startSessionMonitor(options?)

### Description
Starts monitoring the session for changes.

### Method
CREATE

### Endpoint
auth.startSessionMonitor(options?)

### Parameters
#### Parameters
- **options** (SessionMonitorOptions) - Optional - The session monitor options.

### Response
#### Success Response (200)
- **SessionMonitorHandle** - A handle to stop monitoring.

### Response Example
```json
{
  "handle": {}
}
```

--------------------------------

### Static callback page (shoo/callback/index.html)

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Static callback page for Shoo sign-in. Loads shoo.js with data-shoo-auto-callback="false" and manually calls window.Shoo.handleCallback() to exchange the code, save the token, and return to the start page. On failure, shows a cancellation message with a link back to the app. Must be served at /shoo/callback (or a custom path).

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Signing in…</title>
    <script src="https://shoo.dev/shoo.js" data-shoo-auto-callback="false"></script>
  </head>
  <body>
    <p id="status">Signing in…</p>
    <script>
      // Exchanges the code, saves the token, and returns to the start page.
      window.Shoo.handleCallback().catch(() => {
        document.getElementById("status").innerHTML =
          'Sign-in was cancelled or failed. <a href="/">Back to the app</a>';
      });
    </script>
  </body>
</html>
```

--------------------------------

### useShooAuth full example with sign-in and sign-out

Source: https://docs.shoo.dev/docs/api-reference/shoo-react

A complete component using useShooAuth to handle loading, sign-in, sign-out, and displaying identity and claims. Handles errors and expired sessions.

```tsx
import { useShooAuth } from "@shoojs/react";

export function Profile() {
  const { status, identity, claims, error, signIn, clearIdentity } = useShooAuth();

  if (status === "loading") return <p>Loading…</p>;
  if (status !== "signed_in") {
    return (
      <div>
        {error && <p role="alert">{error}</p>}
        <button
          onClick={() => {
            void signIn().catch(() => {
              // The hook sets error, which is rendered above.
            });
          }}
        >
          {status === "expired" ? "Sign in again" : "Sign in"}
        </button>
      </div>
    );
  }

  return (
    <div>
      <p>ID: {identity.userId}</p>
      {claims?.email && <p>Email: {claims.email}</p>}
      <button onClick={clearIdentity}>Sign out</button>
    </div>
  );
}
```

--------------------------------

### parseCallback usage example

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Shows how to use parseCallback to handle the callback result. Check which field is set before reading it, as it returns a union of { code, state }, { error, state }, or null.

```javascript
import { parseCallback } from "@shoojs/auth";

const callback = parseCallback();
if (callback?.error) showError(callback.error);
else if (callback) console.log(callback.code);
```

--------------------------------

### Account component with useShooAuth and Me component

Source: https://docs.shoo.dev/docs/getting-started

Use this snippet to add sign-in to a page. It uses useShooAuth to get identity, status, error, signIn, and clearIdentity. The Me component fetches /api/me with the token and handles 401, non-OK, and network errors. Render <Account /> from any page. Note: Me does not call clearIdentity() on a 401 to avoid clearing a newer sign-in from another tab.

```tsx
"use client";

import { useState } from "react";
import { useShooAuth } from "@shoojs/react";

export function Account() {
  const { identity, status, error, signIn, clearIdentity } = useShooAuth();

  function startSignIn() {
    // If sign-in cannot start, the hook sets `error`.
    signIn().catch(() => undefined);
  }

  if (status === "loading") return <p>Loading…</p>;

  return (
    <div>
      {status === "signed_in" && identity.token ? (
        <>
          <Me key={identity.token} token={identity.token} onSignIn={startSignIn} />
          <button onClick={clearIdentity}>Sign out</button>
        </>
      ) : (
        <button onClick={startSignIn}>{status === "expired" ? "Sign in again" : "Sign in"}</button>
      )}
      {error && <p>Sign-in failed: {error}</p>}
    </div>
  );
}

// Render with `key={token}`. A new token remounts it, so old results and late
// responses for the previous token never show.
function Me({ token, onSignIn }: { token: string; onSignIn: () => void }) {
  const [message, setMessage] = useState<string | null>(null);
  const [rejected, setRejected] = useState(false);

  async function loadMe() {
    setMessage(null);
    try {
      const res = await fetch("/api/me", {
        headers: { Authorization: `Bearer ${token}` }
      });
      if (res.status === 401) {
        // Expired or revoked.
        setRejected(true);
        return;
      }
      if (!res.ok) {
        setMessage(`Request failed (${res.status}). Try again.`);
        return;
      }
      const body: { userId: string } = await res.json();
      setMessage(`Server says you are ${body.userId}`);
    } catch {
      // Network error or a response that is not JSON.
      setMessage("Could not load your account. Try again.");
    }
  }

  if (rejected) return <button onClick={onSignIn}>Sign in again</button>;
  return (
    <>
      <button onClick={() => void loadMe()}>Load my account</button>
      {message && <p>{message}</p>}
    </>
  );
}

```

--------------------------------

### Add callback page at app/auth/callback/page.tsx

Source: https://docs.shoo.dev/docs/getting-started

Next.js App Router page for the default /auth/callback route. The hook exchanges the code once, saves the token, and returns to the page where sign-in started. Use a dedicated callback path; do not reuse a page that does other work or forwards its query string.

```tsx
"use client";

import { useShooAuth } from "@shoojs/react";

export default function ShooCallback() {
  const { error } = useShooAuth();
  if (error) {
    return (
      <p>
        Sign-in was cancelled or failed. <a href="/">Go back</a>
      </p>
    );
  }
  return <p>Signing in…</p>;
}
```

--------------------------------

### Add a sign-in button with startSignIn

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Attach a click handler to a button that calls window.Shoo.startSignIn(). This creates a PKCE verifier and state, saves them in sessionStorage, and navigates to Shoo, returning to the current page after sign-in.

```html
<button id="sign-in">Sign in</button>
<script>
  document.getElementById("sign-in").addEventListener("click", () => {
    // Returns to the current page after sign-in.
    window.Shoo.startSignIn();
  });
</script>
```

--------------------------------

### auth.startSignIn(params?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Saves a sign-in transaction in sessionStorage and navigates to Shoo. Accepts optional parameters to request PII, specify a return path, provide a custom PKCE bundle, or override per-sign-in settings.

```APIDOC
## [POST] auth.startSignIn(params?)

### Description
Saves a sign-in transaction in `sessionStorage` and navigates to Shoo.

### Method
POST

### Endpoint
auth.startSignIn

### Parameters
#### Request Body
- **requestPii** (boolean) - Optional - Request profile data for this sign-in
- **returnTo** (string) - Optional - Same-origin path to return to. Default: current page.
- **bundle** (PkceBundle) - Optional - Use your own PKCE bundle
- **redirectUri** (string) - Optional - Per-sign-in override. Saved with the transaction.
- **clientId** (string) - Optional - Per-sign-in override. Saved with the transaction.
- **shooBaseUrl** (string) - Optional - Per-sign-in override. Saved with the transaction.

### Request Example
```json
{
  "requestPii": true,
  "returnTo": "/settings"
}
```

### Response
#### Success Response (200)
No response body documented.

### Error Handling
Rejects without navigating if storage is not writable.
```

--------------------------------

### Request profile data with startSignIn()

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Call window.Shoo.startSignIn({ requestPii: true }) to request profile data during sign-in. Shoo asks the user before sharing email, name, picture, and pii_sub.

```javascript
window.Shoo.startSignIn({ requestPii: true });
```

--------------------------------

### createPkceBundle()

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Creates a PKCE bundle containing a random state, verifier, and S256 challenge.

```APIDOC
## createPkceBundle()

### Description
Creates a PKCE bundle with a random state, verifier, and S256 challenge.

### Method
Function

### Signature
`createPkceBundle()`

### Returns
- **state** (string) - Random state value
- **verifier** (string) - PKCE verifier
- **challenge** (string) - S256 challenge derived from the verifier
```

--------------------------------

### Configure self-hosted script with data-shoo-base-url

Source: https://docs.shoo.dev/docs/getting-started-vanilla

If you serve a copy of shoo.js from your own origin, set the Shoo server on the script tag using data-shoo-base-url. Otherwise the link opens without PKCE and Shoo rejects it.

```html
<script src="/shoo.js" data-shoo-base-url="https://shoo.dev"></script>
```

--------------------------------

### Plain link for sign-in

Source: https://docs.shoo.dev/docs/getting-started-vanilla

A plain link to the Shoo authorize endpoint also works. The script adds PKCE and state when the link is clicked, but only for links to its own Shoo server. If the link opens without PKCE, Shoo rejects it.

```html
<a href="https://shoo.dev/authorize?redirect_uri=https://your-app.com/shoo/callback">Sign in</a>
```

--------------------------------

### createShooAuth(options)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Creates a browser client for Shoo authentication. Call it in the browser, not during server rendering.

```APIDOC
## createShooAuth(options)

### Description
Creates a browser client for Shoo authentication. Call it in the browser, not during server rendering.

### Method
createShooAuth

### Parameters
#### Options
- **shooBaseUrl** (string) - Optional - Shoo server URL. Default: `"https://shoo.dev"`
- **callbackPath** (string) - Optional - Path Shoo redirects to after sign-in. Default: `"/auth/callback"`
- **redirectUri** (string) - Optional - Full callback URL. Default: Origin + `callbackPath`
- **clientId** (string) - Optional - Derived from `redirectUri`. Do not change. Default: `"origin:<redirect origin>"`
- **requestPii** (boolean) - Optional - Request profile data on every sign-in. Default: `false`
- **storageKey** (string) - Optional - `localStorage` key for the identity. Default: `"shoo_identity"`
- **pkceStorageKey** (string) - Optional - `sessionStorage` prefix for sign-in state. Default: `"shoo_pkce"`
- **returnToStorageKey** (string) - Optional - Deprecated. Has no effect. Default: `"shoo_return_to"`
- **fallbackPath** (string) - Optional - Return path when none is stored. Default: `"/"`

### Request Example
```
import { createShooAuth } from "@shoojs/auth";

const auth = createShooAuth({ callbackPath: "/auth/callback" });
```

### Notes
- The hosted script uses `/shoo/callback` by default. The npm package uses `/auth/callback`.
- The return path is saved inside the sign-in transaction, under `pkceStorageKey`. `returnToStorageKey` is still accepted so old code compiles. Remove it from your code.
```

--------------------------------

### auth.startSessionMonitor(options?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Runs checkSession on an interval. Returns a monitor object with a stop method. Results after stop or token change are ignored.

```APIDOC
## auth.startSessionMonitor(options?)

### Description
Runs `checkSession` on an interval. Returns a monitor object with a `stop()` method. Results that arrive after `stop()` or after the token changes are ignored.

### Parameters
- **options** (object) - Optional
  - **intervalMs** (number) - Default: `60000` - Check interval in milliseconds
  - **immediate** (boolean) - Default: `true` - Check once at start
  - **onResult** (function) - Optional - Called with every current result
  - **onLoginRequired** (function) - Optional - Called on `revoked`, `expired`, or `invalid_token`
  - **onError** (function) - Optional - Called on network or server errors

### Returns
- **monitor** (object) - Contains a `stop()` method to stop monitoring.

### Example
```js
const monitor = auth.startSessionMonitor({
  onLoginRequired: () => auth.clearIdentity()
});
monitor.stop();
```
```

--------------------------------

### Netlify rewrite for /shoo/callback

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Netlify redirect rule that serves index.html at /shoo/callback. Place in public/_redirects. The index.html must load shoo.js.

```plaintext
/shoo/callback  /index.html  200
```

--------------------------------

### Create Shoo auth client with createShooAuth

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Creates a browser client for Shoo authentication. Call it in the browser, not during server rendering. The callbackPath option defaults to "/auth/callback".

```javascript
import { createShooAuth } from "@shoojs/auth";

const auth = createShooAuth({ callbackPath: "/auth/callback" });
```

--------------------------------

### Set APP_ORIGIN in .env.local

Source: https://docs.shoo.dev/docs/getting-started

Set your app origin in .env.local. In production, set APP_ORIGIN to your exact production origin (e.g., https://app.example.com). Each origin is a separate Shoo app with separate user IDs.

```plaintext
APP_ORIGIN=http://localhost:3000
```

--------------------------------

### createShooAuth(options)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Creates a ShooAuthClient instance with the provided options. This is the main entry point for the client-side authentication library.

```APIDOC
## createShooAuth(options)

### Description
Creates a new ShooAuthClient instance with the given options.

### Method
CREATE

### Endpoint
createShooAuth(options)

### Parameters
#### Parameters
- **options** (ShooAuthOptions) - Required - The configuration options for the client.

### Response
#### Success Response (200)
- **ShooAuthClient** - The created client instance.

### Response Example
```json
{
  "client": {}
}
```
```

--------------------------------

### auth.finishSignIn(params?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Completes the sign-in process. This finalizes the authentication and stores the session.

```APIDOC
## auth.finishSignIn(params?)

### Description
Completes the sign-in process. This finalizes the authentication and stores the session.

### Method
CREATE

### Endpoint
auth.finishSignIn(params?)

### Parameters
#### Parameters
- **params** (FinishSignInOptions) - Optional - The finish sign-in options.

### Response
#### Success Response (200)
- **void** - No return value.

### Response Example
```json
{}
```

--------------------------------

### Vercel rewrite for /shoo/callback

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Vercel rewrite configuration in vercel.json that serves index.html at /shoo/callback. The index.html must load shoo.js.

```json
{
  "rewrites": [{ "source": "/shoo/callback", "destination": "/index.html" }]
}
```

--------------------------------

### Request profile data with signIn

Source: https://docs.shoo.dev/docs/getting-started

Call signIn with the requestPii option set to true to request access to the user's email, name, picture, and pii_sub. Shoo will ask the user for permission before sharing this data.

```javascript
signIn({ requestPii: true });
```

--------------------------------

### Create Shoo Convex auth adapter in src/shoo.ts

Source: https://docs.shoo.dev/docs/convex

Creates the Shoo authentication adapter for Convex. The adapter is safe to import during server rendering and creates the browser client after mount.

```typescript
import { createShooConvexAuth } from "@shoojs/react";

export const { useAuth, signIn, signOut } = createShooConvexAuth({
  callbackPath: "/shoo/callback"
});
```

--------------------------------

### createSignInUrl(params)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Builds an /authorize URL without navigating. Use this to construct a sign-in URL programmatically.

```APIDOC
## createSignInUrl(params)

### Description
Builds an /authorize URL without navigating. Use this to construct a sign-in URL programmatically.

### Method
Function

### Signature
`createSignInUrl(params)`

### Parameters
- **params** (object) - Required - Parameters for building the authorize URL
```

--------------------------------

### Add the hosted Shoo script

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Load the hosted script on every page that signs users in or reads identity. Load it once per page and do not also bundle @shoojs/auth on the same page.

```html
<script src="https://shoo.dev/shoo.js"></script>
```

--------------------------------

### createShooConvexAuth(options)

Source: https://docs.shoo.dev/docs/api-reference/shoo-react

Creates a Convex authentication object with useAuth, signIn, and signOut. Call once at module scope and pass useAuth to ConvexProviderWithAuth.

```APIDOC
## createShooConvexAuth(options)

### Description
Call once at module scope. Pass `useAuth` to `ConvexProviderWithAuth`. See the Convex guide.

### Parameters
- **options** (object) - Required - Configuration options.
  - `callbackPath` (string) - Required - The path to the Shoo callback endpoint.

### Return Value
- `useAuth` (() => ShooConvexAuthState) - Hook for `ConvexProviderWithAuth`.
- `signIn` ((opts?: StartSignInOptions) => Promise<void>) - Navigate to Shoo.
- `signOut` (() => void) - Clear the stored identity. All consumers update.

### Example
ts
import { createShooConvexAuth } from "@shoojs/react";

export const { useAuth, signIn, signOut } = createShooConvexAuth({
  callbackPath: "/shoo/callback"
});


```

--------------------------------

### nginx rewrite for /shoo/callback

Source: https://docs.shoo.dev/docs/getting-started-vanilla

nginx location block that serves index.html for the exact /shoo/callback path. The index.html must load shoo.js.

```nginx
location = /shoo/callback {
  try_files /index.html =404;
}
```

--------------------------------

### Connect Shoo provider with ConvexProviderWithAuth in src/main.tsx

Source: https://docs.shoo.dev/docs/convex

Replaces ConvexProvider with ConvexProviderWithAuth in the entry file to connect the Shoo auth provider. Uses the useAuth hook from the adapter created in src/shoo.ts.

```tsx
import { ConvexProviderWithAuth, ConvexReactClient } from "convex/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import { useAuth } from "./shoo";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ConvexProviderWithAuth client={convex} useAuth={useAuth}>
      <App />
    </ConvexProviderWithAuth>
  </StrictMode>
);
```

--------------------------------

### auth.handleCallback(params?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Run on the callback page. Exchanges the code, saves the identity, removes callback parameters from the URL, and navigates to the return path. Returns null when the URL has no callback parameters.

```APIDOC
## [POST] auth.handleCallback(params?)

### Description
Run on the callback page. Exchanges the code, saves the identity, removes callback parameters from the URL, and navigates to the return path.

### Method
POST

### Endpoint
auth.handleCallback

### Parameters
#### Query Parameters
- **url** (string) - Optional - URL to read. Default: current URL.
- **redirectTo** (string) - Optional - Same-origin path that overrides the stored return path
- **returnTo** (string) - Optional - Alias for `redirectTo`
- **fallbackPath** (string) - Optional - Used when no return path is stored

### Request Example
```json
{
  "url": "https://example.com/callback?code=abc",
  "redirectTo": "/dashboard"
}
```

### Response
#### Success Response (200)
Returns `null` when the URL has no callback parameters.

### Error Handling
Throws when the user denied access, the state does not match, the transaction expired (10 minutes), or the exchange failed. A denial, expiry, or failed exchange removes the stored transaction. A callback with an unknown state leaves other pending sign-ins alone.
```

--------------------------------

### auth.finishSignIn(params?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Same exchange as handleCallback, but does not navigate unless redirectAfter: true. Accepts options to control callback parameter cleanup and navigation.

```APIDOC
## [POST] auth.finishSignIn(params?)

### Description
Same exchange as handleCallback, but does not navigate unless `redirectAfter: true`.

### Method
POST

### Endpoint
auth.finishSignIn

### Parameters
#### Query Parameters
- **clearCallbackParams** (boolean) - Optional - Remove callback parameters from the URL. Default: `true`.
- **redirectAfter** (boolean) - Optional - Navigate to the return path after the exchange. Default: `false`.
- **consumeReturnTo** (boolean) - Optional - **Deprecated.** Has no effect.
- **url** (string) - Optional - URL to read. Default: current URL.
- **redirectTo** (string) - Optional - Same-origin path that overrides the stored return path
- **returnTo** (string) - Optional - Alias for `redirectTo`
- **fallbackPath** (string) - Optional - Used when no return path is stored

### Request Example
```json
{
  "clearCallbackParams": true,
  "redirectAfter": false
}
```

### Response
#### Success Response (200)
No response body documented.

### Error Handling
The transaction is always removed after the exchange, so `consumeReturnTo` does nothing.
```

--------------------------------

### auth.handleCallback(params?)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Handles the callback from the authentication provider. This processes the authorization code and exchanges it for tokens.

```APIDOC
## auth.handleCallback(params?)

### Description
Handles the callback from the authentication provider. This processes the authorization code and exchanges it for tokens.

### Method
CREATE

### Endpoint
auth.handleCallback(params?)

### Parameters
#### Parameters
- **params** (HandleCallbackOptions) - Optional - The callback handling options.

### Response
#### Success Response (200)
- **void** - No return value.

### Response Example
```json
{}
```

--------------------------------

### useShooAuth basic usage

Source: https://docs.shoo.dev/docs/api-reference/shoo-react

Import useShooAuth and render the current authentication status. The hook returns an object with status and other properties.

```tsx
import { useShooAuth } from "@shoojs/react";

export function AuthStatus() {
  const { status } = useShooAuth();
  return <p>{status}</p>;
}
```

--------------------------------

### Call your backend with the token

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Retrieve the token from getIdentity() and send it in the Authorization header of a fetch request to your backend. Your backend must verify the token.

```javascript
const { token } = window.Shoo.getIdentity();
const res = await fetch("/api/me", {
  headers: { Authorization: `Bearer ${token}` }
});
```

--------------------------------

### Server helper with authorizationCheck: "required"

Source: https://docs.shoo.dev/docs/tokens-and-sessions

Creates a server-side verifier that checks the token offline and then asks Shoo whether the app is still approved. Denies access on revocation, errors, and timeouts. Use only for sensitive actions such as payments, deletes, or permission changes.

```typescript
import { createShooVerifier } from "@shoojs/auth/server";

export const verifyShooTokenOnline = createShooVerifier({
  appOrigin: process.env.APP_ORIGIN!,
  authorizationCheck: "required"
});
```

--------------------------------

### auth.handleCallback() with error handling

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Runs on the callback page to exchange the code, save the identity, remove callback parameters, and navigate to the return path. Returns null when the URL has no callback parameters; throws on denial, state mismatch, expiry (10 minutes), or exchange failure.

```javascript
try {
  await auth.handleCallback();
} catch (error) {
  // Denied, expired, or mismatched sign-in. Offer a retry.
}
```

--------------------------------

### Import createShooVerifier from @shoojs/auth/server

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Imports the server verifier for server-side authentication verification.

```typescript
import { createShooVerifier } from "@shoojs/auth/server";
```

--------------------------------

### Custom callback path with data-shoo-callback-path

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Sets a custom callback path (/auth/callback) on every script tag that loads shoo.js. Required when using the npm package default path with the script.

```html
<script src="https://shoo.dev/shoo.js" data-shoo-callback-path="/auth/callback"></script>
```

--------------------------------

### Read the identity with getIdentity()

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Use window.Shoo.getIdentity() to read the current identity. If identity.userId is present, the user is signed in; otherwise they are signed out. The identity.userId is the pairwise_sub and identity.token is the signed token. An expired or unreadable token reads as signed out.

```javascript
const identity = window.Shoo.getIdentity();
if (identity.userId) {
  console.log("Signed in as", identity.userId);
} else {
  console.log("Signed out");
}
```

--------------------------------

### Create Shoo verifier with createShooVerifier

Source: https://docs.shoo.dev/docs/server-verification

Creates a Shoo token verifier with a fixed app origin and localhost allowed only outside production. The verifier is created once per process to share the key cache.

```typescript
import { createShooVerifier } from "@shoojs/auth/server";

const appOrigin = process.env.APP_ORIGIN;
if (!appOrigin) throw new Error("APP_ORIGIN is not set");

// Create once per process so the key cache is shared.
export const verifyShooToken = createShooVerifier({
  appOrigin,
  // Allows http://localhost only outside production.
  allowLocalhost: process.env.NODE_ENV !== "production"
});
```

--------------------------------

### useAuth()

Source: https://docs.shoo.dev/docs/api-reference/shoo-react

Hook returned by createShooConvexAuth that provides authentication state and token access for Convex.

```APIDOC
## useAuth()

### Description
Hook for `ConvexProviderWithAuth`. Returns authentication state and a token fetcher.

### Return Value
- `isLoading` (boolean) - `true` until the client is ready.
- `isAuthenticated` (boolean) - `true` when `status === "signed_in"`.
- `fetchAccessToken` ((args) => Promise<string | null>) - The stored token, or `null`. Never navigates.
- `status` (ShooAuthStatus) - Same values as `useShooAuth`.
- `error` (string | null) - Last callback error.

### Behavior
`fetchAccessToken` gets a new reference when the signed-in account changes, so Convex sets the new token. It never starts a sign-in.

```

--------------------------------

### Set APP_ORIGIN environment variable for Convex deployments

Source: https://docs.shoo.dev/docs/convex

Sets the APP_ORIGIN environment variable for both development and production deployments. Do not set a localhost or preview origin on the production deployment; users from different origins have different IDs. Set APP_ORIGIN before pushing the auth config because the config throws without it.

```bash
# Development deployment
npx convex env set APP_ORIGIN http://localhost:5173

# Production deployment
npx convex env --prod set APP_ORIGIN https://app.example.com
```

--------------------------------

### auth.startSessionMonitor(options?) - periodic session checks

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Runs checkSession on an interval. Defaults: intervalMs 60000, immediate true. Options include onResult, onLoginRequired (called on revoked, expired, or invalid_token), and onError. Results after stop() or after the token changes are ignored.

```javascript
const monitor = auth.startSessionMonitor({
  onLoginRequired: () => auth.clearIdentity()
});
monitor.stop();
```

--------------------------------

### Import Shoo auth types from @shoojs/auth

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Imports the TypeScript types for Shoo authentication, including options, callbacks, and session monitoring.

```typescript
import type {
  CheckSessionOptions,
  ExchangeCodeParams,
  FinishSignInOptions,
  HandleCallbackOptions,
  PkceBundle,
  SessionCheckResult,
  SessionMonitorHandle,
  SessionMonitorOptions,
  ShooAuthClient,
  ShooAuthOptions,
  ShooCallback,
  ShooIdentity,
  StartSignInOptions
} from "@shoojs/auth";
```

--------------------------------

### Create online verifier with authorizationCheck required

Source: https://docs.shoo.dev/docs/server-verification

Adds an online verifier that requires Shoo to confirm the app is still approved. Use for sensitive actions like payments, deletes, and permission changes; it makes one request per call and denies when Shoo is unreachable.

```typescript
export const verifyShooTokenOnline = createShooVerifier({
  appOrigin,
  allowLocalhost: process.env.NODE_ENV !== "production",
  authorizationCheck: "required"
});
```

--------------------------------

### Subscribe to identity changes with subscribe()

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Use window.Shoo.subscribe() to update your UI when the identity changes, including from another tab or on expiry. The callback receives the identity object.

```javascript
const unsubscribe = window.Shoo.subscribe((identity) => {
  render(identity.userId);
});
```

--------------------------------

### Configure Convex auth with custom JWT provider

Source: https://docs.shoo.dev/docs/convex

Set up Convex's auth.config.ts to use Shoo as a custom JWT provider. The applicationID is required; without it, Convex skips the audience check and accepts tokens from any Shoo app.

```typescript
import type { AuthConfig } from "convex/server";

// Your frontend origin, not the *.convex.cloud or *.convex.site URL.
const appOrigin = process.env.APP_ORIGIN;
if (!appOrigin) throw new Error("Set APP_ORIGIN in this Convex deployment");

export default {
  providers: [
    {
      type: "customJwt",
      issuer: "https://shoo.dev",
      jwks: "https://shoo.dev/.well-known/jwks.json",
      algorithm: "ES256",
      // Required. Without it, Convex accepts tokens issued to any Shoo app.
      applicationID: `origin:${new URL(appOrigin).origin}`
    }
  ]
} satisfies AuthConfig;
```

--------------------------------

### Request profile data on every sign-in with data-shoo-scope

Source: https://docs.shoo.dev/docs/getting-started-vanilla

Add the data-shoo-scope attribute to the Shoo script tag to request profile data on every sign-in. Shoo asks the user before sharing email, name, picture, and pii_sub.

```html
<script src="https://shoo.dev/shoo.js" data-shoo-scope="profile email"></script>
```

--------------------------------

### POST /session/check

Source: https://docs.shoo.dev/docs/server-verification

Online verification endpoint that checks with Shoo if the app is still approved. Denies access if Shoo cannot answer.

```APIDOC
## [POST] /session/check

### Description
Checks online whether the app is still approved and the token is valid. Denies access if Shoo cannot answer.

### Method
POST

### Endpoint
/session/check

### Response
#### Success Response (200)
- No response body documented.

#### Error Response
- Returns an error if the token is invalid or the app is not approved.
```

--------------------------------

### createShooVerifier()

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Creates a server-side verifier for verifying authentication tokens.

```APIDOC
## createShooVerifier()

### Description
Creates a server-side verifier for verifying authentication tokens.

### Method
CREATE

### Endpoint
createShooVerifier()

### Parameters
None

### Response
#### Success Response (200)
- **object** - The verifier object.

### Response Example
```json
{
  "verifier": {}
}
```

--------------------------------

### Protect API route with Shoo verifier

Source: https://docs.shoo.dev/docs/getting-started

Protect the API route by creating a verifier in lib/shoo.ts and using it in the /api/me route. The verifier requires APP_ORIGIN to be set and disables localhost in production. The route extracts a Bearer token and returns 401 if missing or invalid.

```typescript
import { createShooVerifier } from "@shoojs/auth/server";

const appOrigin = process.env.APP_ORIGIN;
if (!appOrigin) throw new Error("APP_ORIGIN is not set");

export const verifyShooToken = createShooVerifier({
  appOrigin,
  allowLocalhost: process.env.NODE_ENV !== "production"
});
```

```typescript
import { verifyShooToken } from "@/lib/shoo";

export async function GET(request: Request) {
  const match = /^Bearer (\S+)$/.exec(request.headers.get("authorization") ?? "");
  if (!match) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }

  try {
    const identity = await verifyShooToken(match[1]);
    // Use identity.userId as the user ID in your database.
    return Response.json({ userId: identity.userId });
  } catch {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }
}
```

--------------------------------

### auth.subscribe(listener)

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Subscribes to changes in the authentication state. The listener is called when the identity changes.

```APIDOC
## auth.subscribe(listener)

### Description
Subscribes to changes in the authentication state. The listener is called when the identity changes.

### Method
CREATE

### Endpoint
auth.subscribe(listener)

### Parameters
#### Parameters
- **listener** (Function) - Required - The listener function to call on changes.

### Response
#### Success Response (200)
- **void** - No return value.

### Response Example
```json
{}
```

--------------------------------

### auth.checkSession()

Source: https://docs.shoo.dev/docs/api-reference/shoo-auth

Checks the current session status.

```APIDOC
## auth.checkSession()

### Description
Checks the current session status.

### Method
READ

### Endpoint
auth.checkSession()

### Parameters
None

### Response
#### Success Response (200)
- **SessionCheckResult** - The session check result.

### Response Example
```json
{
  "result": {}
}
```
Tokens:
Raw