Gatsby

The @authdog/gatsby SDK provides browser callback utilities and a requireAuth gate for Gatsby Functions.

Install

npm install @authdog/gatsby @authdog/react-elements

yarn add @authdog/gatsby @authdog/react-elements

pnpm add @authdog/gatsby @authdog/react-elements

bun add @authdog/gatsby @authdog/react-elements

deno add npm:@authdog/gatsby npm:@authdog/react-elements

Requires Gatsby ^5 and React 18 or 19. The @authdog/react-elements package supplies the drop-in UI and its stylesheet.

Handle the browser callback

AuthdogProvider only strips ?token= and reloads. It does not validate, persist, or exchange the token, so it does not make a session available. To retain the callback token for API calls, run initAuthdog() instead:

// gatsby-browser.js
import React, { useEffect } from "react"
import { initAuthdog } from "@authdog/gatsby/client"

function AuthdogBootstrap({ children }) {
  useEffect(() => {
    initAuthdog()
  }, [])
  return children
}

export const wrapRootElement = ({ element }) => {
  return <AuthdogBootstrap>{element}</AuthdogBootstrap>
}

initAuthdog() stores tokens that match JWT structure in localStorage; this is not cryptographic validation. Set GATSBY_AUTHDOG_PUBLIC_KEY for browser configuration. Do not mount AuthdogProvider around this bootstrap because it can remove the token first.

Protect a Function

createAuthdog runs on the server with your environment's public key (pk_..., server-only via PK_AUTHDOG). requireAuth accepts either Authorization: Bearer <token> or an authdog-session cookie, validates it through userinfo, returns 401 on failure, and attaches req.authdog on success:

// src/api/me.ts
import { createAuthdog } from "@authdog/gatsby/server"

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

export default authdog.requireAuth(async (req, res) => {
  res.status(200).json({ user: req.authdog?.user ?? null })
})

Send the browser token explicitly when calling a Function:

import { initAuthdog } from "@authdog/gatsby/client"

const token = initAuthdog()
const response = await fetch("/api/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.

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

// src/api/logout.ts
export { logoutHandler as default } from "@authdog/gatsby/server"

When using the bearer/local-storage flow, also call clearAuthdogToken() in the browser. Treat requireAuth in Functions as the security boundary and pair it with your authorization model.

Next steps

• Component reference: the @authdog/react-elements UI.
• Backend requests: the verification model, in depth.
• Resource library: runnable example for this stack.