redwood

---
name: redwood
description: Add authdog to a RedwoodJS app with @authdog/redwood — initAuthdog browser callback + localStorage token on the web side, and an api-side requireAuth gate for RedwoodJS Functions and services. Use when the user asks to integrate authdog auth into a RedwoodJS app.
---

# authdog for RedwoodJS

The `@authdog/redwood` SDK provides browser callback utilities and an API-side `requireAuth` gate for RedwoodJS Functions and services.

## When to use this skill

The user wants to add "Sign in with authdog" (or authdog session handling) to a RedwoodJS app (React 18 or 19). The package exposes `@authdog/redwood/web` and `@authdog/redwood/api`.

## What you need from the user first

Their authdog **public key** (`pk_...`). Browser config uses `REDWOOD_ENV_AUTHDOG_PUBLIC_KEY`; api config uses `PK_AUTHDOG`.

## Steps

### 1. Install

```bash
yarn workspace web add @authdog/redwood @authdog/react-elements
yarn workspace api add @authdog/redwood
```

### 2. Configure environment variables

Expose browser configuration as `REDWOOD_ENV_AUTHDOG_PUBLIC_KEY` and add it to `includeEnvironmentVariables` in `redwood.toml`. Set `PK_AUTHDOG` (server-only) on the api workspace.

### 3. Handle the web callback

```tsx
// web/src/App.tsx
import { useEffect } from "react"
import { initAuthdog } from "@authdog/redwood/web"
import { RedwoodProvider } from "@redwoodjs/web"
import Routes from "src/Routes"

const App = () => {
  useEffect(() => {
    initAuthdog()
  }, [])

  return (
    <RedwoodProvider titleTemplate="%PageTitle | %AppTitle">
      <Routes />
    </RedwoodProvider>
  )
}
```

`initAuthdog()` strips `?token=`, stores values that match JWT structure in `localStorage`, and reloads. This is not cryptographic validation. The exported `AuthdogProvider` only strips the token and reloads; it does not persist or exchange it, so do not wrap this bootstrap with that provider.

### 4. Protect a Function

On the api side, `createAuthdog` uses your environment's **public key** (`pk_...`, server-only via `PK_AUTHDOG`). `requireAuth` accepts either `Authorization: Bearer ` or an `authdog-session` cookie, validates it through userinfo, returns `401` on failure, and attaches `event.authdog` on success:

```ts
// api/src/functions/me.ts
import { createAuthdog } from "@authdog/redwood/api"
import type { LambdaEvent } from "@authdog/redwood/api"

const authdog = createAuthdog({ publicKey: process.env.PK_AUTHDOG! })

export const handler = authdog.requireAuth(async (event: LambdaEvent) => ({
  statusCode: 200,
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ user: event.authdog?.user ?? null }),
}))
```

Send the stored token when calling the Function:

```ts
import { initAuthdog } from "@authdog/redwood/web"

const token = initAuthdog()
const response = await fetch("/.redwood/functions/me", {
  headers: token ? { Authorization: `Bearer ${token}` } : {},
})
```

The SDK does not create `authdog-session`; if you prefer an HttpOnly cookie, implement a server callback that validates the token before setting it.

### 5. Sign out

Re-export the logout handler to clear `authdog-session`:

```ts
// api/src/functions/logout.ts
export { logoutHandler as handler } from "@authdog/redwood/api"
```

In services, resolve the user from the GraphQL context: `await authdog.getUser(context.event)`.

When using the bearer/local-storage flow, also call `clearAuthdogToken()` in the browser. Treat `requireAuth` on the api side as the security boundary and pair it with your [authorization](https://www.authdog.com/docs/concepts/authorization) model.

## Gotchas

- **`AuthdogProvider` vs `initAuthdog()`**: the provider only strips `?token=` and reloads; it does not persist the token. Use `initAuthdog()` to keep the token for API calls. Don't wrap the bootstrap with the provider.
- **No `authdog-session` cookie by default**: the SDK stores the token in `localStorage` and sends it as a bearer. Build the server callback yourself if you want an HttpOnly cookie.
- **`requireAuth` on the api side is the security boundary**: client-side state is not. Resolve the user from GraphQL context (`authdog.getUser(context.event)`) in services.

## Next steps

- [Component reference](https://www.authdog.com/docs/components): the `@authdog/react-elements` UI.
- [Backend requests](https://www.authdog.com/docs/backend): the verification model, in depth.

More agent context in authdog/agent-skills

31 other files this repository gives its agents.