The authfy npm package

Reusable client for the Authfy OAuth2 / OIDC Authorization Code + PKCE flow, built with Vite + TypeScript. Ships ESM + CJS with full types.

Designed for Next.js (App Router) with a turn-key adapter, but the core is framework-agnostic. Config and cookies are injected — the library never reads process.env or touches document.cookie itself, so it is SSR/edge safe.

Install

npm install authfy

Official package page: npmjs.com/package/authfy

For the React hooks (authfy/react) you also need react and react-dom (peer dependencies). The package source lives in this repo under react-package/.

Quick start (Next.js) — zero config

Two files in your app plus .env. That's it.

1. Set .env

Create an access key for your application on the support console's Access keys page and copy its public key into APP_PUBLIC_KEY — it is the sole client credential (since v0.2.0 there is no clientId/AUTH_APP_ID; the package derives the key_id for authorize/logout redirects from the public key automatically). The library reads these automatically — nothing is hardcoded:

APP_URL=http://localhost:3004
AUTH_API_URL=http://localhost:8081
AUTH_VIEW_URL=http://localhost:3001
APP_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

APP_PUBLIC_KEY accepts any of three shapes — a quoted multi-line PEM pasted exactly as the support console shows it, a single line with \n escapes (as above), or the bare base64 body without the BEGIN/END markers. The package normalizes whichever you use before deriving key_id and before sending the X-App-Public-Key header.

redirect_uri is derived from APP_URL, so the APP_URL origin must appear in the access key's Allowed URLs — one URL per line, including the local one you develop against:

https://hrm.example.com
http://localhost:3004

If it is missing, sign-in stops on "The return address is not set up correctly" before the user ever reaches your app.

2. Add one catch-all route file

Next.js routing is file-system based, so this one file must exist in your app (a package in node_modules can't create it for you). It's a single line — it handles start, callback, refresh, logout, and session for you:

// app/api/authy/[...authy]/route.ts
export { GET, POST } from "authfy/next/auto";

That's the entire server setup — no lib/authy.ts, no per-route files. Config is read from .env, and the API/PKCE/refresh/logout are all wired internally.

3. Wrap the app

// app/layout.tsx
import { AuthyProvider } from "authfy/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthyProvider>{children}</AuthyProvider>
      </body>
    </html>
  );
}

4. Use it in components

"use client";
import { useAuthy } from "authfy/react";

export function AccountBadge() {
  const { user, authenticated, status, logout } = useAuthy();

  if (status === "loading") return <span>Loading…</span>;
  if (!authenticated) return <a href="/api/authy/start">Sign in</a>;
  return <button onClick={() => logout()}>{user?.name ?? user?.email} — Sign out</button>;
}

Protect a subtree:

"use client";
import { AuthGuard } from "authfy/react";

export default function Protected({ children }: { children: React.ReactNode }) {
  return <AuthGuard>{children}</AuthGuard>;
}

Tokens never reach browser JS — useAuthy() only exposes user and authenticated. Tokens stay in the HTTP-only authy_session cookie.

Silent refresh in the proxy

Next.js 16 replaced middleware.ts with proxy.ts (exporting proxy). authy.proxy returns a redirect when the access token is about to expire, or null to continue:

// proxy.ts  (Next.js 16)
import { NextResponse, type NextRequest } from "next/server";
import { proxy as authyProxy } from "authfy/next/auto";

export function proxy(request: NextRequest) {
  return authyProxy(request) ?? NextResponse.next();
}

export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\..*).*)"] };

Read the verified session on the server

import { cookies } from "next/headers";
import { authy } from "authfy/next/auto";

export default async function Page() {
  const store = await cookies();
  const session = await authy().getServerSession({ get: (name) => store.get(name)?.value });
  if (!session) return null;
  return <pre>{session.scope}</pre>; // session.accessToken is verified, server-only
}

Call Authfy external APIs with that session:

const company = await authy().server.api.getExternalCompany(session); // { ok, status, data, error }

Explicit config (instead of auto)

If you'd rather inject config yourself — multi-tenant, a secrets manager, or tests — skip authfy/next/auto and build the adapter once:

// lib/authy.ts
import { configFromEnv } from "authfy";
import { createAuthyNext } from "authfy/next";

export const authy = createAuthyNext({ config: configFromEnv(process.env) });

Then either re-export the catch-all dispatcher from one file:

// app/api/authy/[...authy]/route.ts
import { authy } from "@/lib/authy";
export const GET = authy.route.GET;
export const POST = authy.route.POST;

…or mount one file per route with authy.handlers.start, .callback, .refresh, .logout, .session if you prefer them split out.

Configuration reference

createAuthyNext({ config, ... }) takes a config from configFromEnv(process.env) or createAuthyConfig({...}):

redirect_uri, the authorize URL, and the logout URL — including their key_id parameter, derived from appPublicKey — are computed automatically. The package sends X-App-Public-Key on token, refresh, revoke, and external API calls, and verifies received tokens by matching the JWT kid to the key's fingerprint. Extra options on createAuthyNext: routePrefix (default /api/authy), logoutPath (default /signed-out), secureCookies (defaults to true on https), and onTokenRefresh.

Token refresh logging

After every successful silent rotation the refreshed access token is logged:

• Server (refresh route): [authfy] Refreshed access token: ... on the server console.
• Browser (AuthyProvider): the same line in the browser console after a POST refresh.

To override or silence it, switch to explicit config and pass onTokenRefresh:

export const authy = createAuthyNext({
  config: configFromEnv(process.env),
  onTokenRefresh: (accessToken) => console.log("[authfy] Refreshed access token:", accessToken),
  // or: onTokenRefresh: () => {}   // silence it
});

Entry points

Local development & linking

npm run dev    # vite build --watch -> dist/
npm run build  # one-off build

Link into a consuming app with npm link authfy, or add both to a workspace ("workspaces": ["authfy", "apps/*"]) and depend on "authfy": "workspace:*".

Deployment note

If your app runs behind a reverse proxy (Nginx, CapRover, etc.) and the OAuth callback returns 502 Bad Gateway while everything else works, the proxy's response-header buffers are likely too small for the session Set-Cookie headers. Raise proxy_buffer_size / proxy_buffers / large_client_header_buffers on the proxy, clear cookies, and start a fresh login — or ask your Authfy administrator for the recommended configuration.