CIRCLE
Getting started

Quick start

A Fastify backend with sign-in, session and a protected route in under fifty lines.

This page builds the smallest working backend: sign-in, session cookie, /auth/me and one protected route. It uses in-memory stores, which are only fit for a demo or a single instance: see Production checklist before deploying.

Prerequisites

  • The SDK installed, with fastify >=5.12.6.
  • An application registered in auth-service with the redirect URI https://app.example.com/auth/callback and a back-channel logout URI https://app.example.com/auth/backchannel-logout.
  • Three values in your environment: AUTH_ISSUER (the auth-service URL), AUTH_CLIENT_SECRET and AUTH_COOKIE_SECRET (at least 32 random characters, for example openssl rand -base64 48).

The server

import Fastify from "fastify";
import {
  GrantManager,
  MemoryGrantStore,
  createAuthClient,
} from "@circle-rd/auth-ai";
import { authPlugin, requireAuth } from "@circle-rd/auth-ai/fastify";
import { MemorySessionStore, createAuthHandlers } from "@circle-rd/auth-ai/web";

// A missing secret must stop the process: an undefined clientSecret would
// silently turn the client into a public one.
function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable ${name}`);
  return value;
}

const auth = createAuthClient({
  issuer: env("AUTH_ISSUER"),
  clientId: "my-app",
  clientSecret: env("AUTH_CLIENT_SECRET"),
  redirectUri: "https://app.example.com/auth/callback",
  postLogoutRedirectUri: "https://app.example.com/auth/logout/callback",
});

const grants = new GrantManager({ auth, store: new MemoryGrantStore() });
const handlers = await createAuthHandlers({
  auth,
  grants,
  sessions: new MemorySessionStore(),
  secret: env("AUTH_COOKIE_SECRET"),
});

const app = Fastify();
await app.register(authPlugin, { handlers });

app.get("/api/profile", { preHandler: requireAuth(handlers) }, async (request) => {
  const { claims } = request.authSession!;
  return { sub: claims.sub, roles: claims.roles ?? [] };
});

await app.listen({ host: "0.0.0.0", port: 3000 });

createAuthClient validates its configuration and throws CFG_001 on any invalid value (a trailing slash on issuer, a non-HTTPS URL, a missing openid scope…). createAuthHandlers also checks that redirectUri ends with <basePath>/callback; basePath defaults to /auth.

What you get

authPlugin serves five routes below /auth:

RouteMethodWhat it does
/auth/loginGETRedirects to auth-service. Accepts ?next=/path (same-origin paths only) and ?prompt=.
/auth/callbackGETCompletes the sign-in, creates the session and redirects to next.
/auth/meGETReturns { user, expiresAt }, or 401 with SES_001 when signed out.
/auth/logoutPOSTEnds the session, then redirects (303) to the provider's logout URL, or answers { logoutUrl } when the request sends Accept: application/json. Without a session the provider's logout URL is still returned, without id_token_hint: the provider asks the user to confirm, then ends the single sign-on session.
/auth/backchannel-logoutPOSTCalled by auth-service to end sessions.

Open https://app.example.com/auth/login?next=/api/profile in a browser: you are sent to auth-service, sign in, and land on /api/profile with a session cookie. The cookie is HttpOnly, Secure, SameSite=Lax and prefixed with __Host- on HTTPS; the browser never sees a token.

Local development works over plain HTTP on loopback: redirectUri may be http://localhost:3000/auth/callback (and only for localhost, 127.0.0.1 or [::1]). The cookies then lose the Secure flag and the __Host- prefix.

Where to go next

Copyright © 2026