@authdog/fastify resolves Authdog sessions on Fastify 4 and 5. Its plugin decorates requests with session context and exposes an authentication guard.
Install
npm install @authdog/fastify fastifyyarn add @authdog/fastify fastifypnpm add @authdog/fastify fastifybun add @authdog/fastify fastifydeno add npm:@authdog/fastify npm:fastify@authdog/fastify is published on npm. fastify is a peer dependency (^4 or ^5); @authdog/node-commons and fastify-plugin install automatically. @fastify/cookie is not required.
Register the plugin
Register once with your environment's public key (pk_...):
import Fastify from "fastify"
import { authdogPlugin } from "@authdog/fastify"
const app = Fastify()
await app.register(authdogPlugin, { publicKey: process.env.PK_AUTHDOG! })The key is safe to expose. Registration rejects malformed keys and identity hosts outside the trusted HTTPS allowlist.
On each request, the plugin prefers the authdog-session cookie, then reads Authorization: Bearer <token>. It calls the environment's OIDC userinfo endpoint and sets request.authdog to { token, user, isAuthenticated }. Only a success envelope (meta.code === 200 with a user) authenticates the request. Missing, invalid, or unverifiable tokens yield anonymous context instead of an application error.
fetchUserInfo: false skips userinfo but does not authenticate token presence. token may be set while user remains null and isAuthenticated remains false. Built-in requireAuth therefore returns 401; use this option only with separate server-side validation and enforcement.
Protect a route
Use app.authdog.requireAuth as a preHandler. It is the security boundary and returns 401 {"error":"Unauthorized"} for anonymous context:
app.get(
"/me",
{ preHandler: app.authdog.requireAuth },
async (req) => req.authdog!.user,
)Authentication identifies a caller; it does not authorize actions. Apply authorization checks after this guard. Client-side checks never protect server routes.
Sign out
app.authdog.logout clears the local cookie and redirects to a sanitized same-origin redirect_uri:
app.get("/logout", (req, reply) => app.authdog.logout(req, reply))This does not revoke a bearer token or end an upstream identity-provider session.
Next steps
- Backend requests
- Express
- Calling the REST API
- Inventory API: runnable example for this stack.