API route handlers

Next.js Pages Router handler factories for standard auth endpoints. Wire in src/pages/api/auth/*.ts.

Session — `createAuthSessionHandler`


// src/pages/api/auth/session.ts
import { createAuthSessionHandler } from '@sumx/ssr-auth-core/next/auth-session-handler';
 
export default createAuthSessionHandler({
  getOidcConfig: () => ({
    authority: process.env.NEXT_PUBLIC_AUTHORITY!,
    clientId: process.env.NEXT_PUBLIC_CLIENT_ID!,
  }),
  fetchPermissionsForReturnPathGate: async (req) => {
    // Portal: BFF getAllPermissions + Set-Cookie headers
    return { data: permissions, setCookieHeaders: [] };
  },
  onAuthenticatedSubjectActivity: async (subject) => {
    // Optional: refresh activity TTL
  },
});

Methods

Method	Behavior
`GET`	Verify session cookie + token cookie; refresh access token if needed
`POST`	Establish session from OIDC tokens (`idToken`, `accessToken`, `refreshToken`)
`DELETE`	Clear session (internal / sync)

Config: `AuthSessionApiConfig`

Field	Required	Description
`fetchPermissionsForReturnPathGate`	Yes	Permissions for return path gate
`getOidcConfig`	No	Defaults to `NEXT_PUBLIC_*` env
`onAuthenticatedSubjectActivity`	No	Hook after successful auth

Rate limiting: 120 req / min / IP (in-memory; per instance).

Logout — `createAuthLogoutHandler`


import { createAuthLogoutHandler } from '@sumx/ssr-auth-core/next/auth-logout-handler';
 
export default createAuthLogoutHandler({
  getOidcConfig: () => ({ ... }),
  // optional: build end-session URL, clear server-side state
});

Default export authLogoutPostHandler uses env-only config for quick setup.

Type: AuthLogoutApiConfig.

OIDC well-known — `createAuthOidcWellKnownHandler`


import { createAuthOidcWellKnownHandler } from '@sumx/ssr-auth-core/next/oidc-well-known-handler';
 
export default createAuthOidcWellKnownHandler({
  getOidcConfig: () => ({ authority, clientId }),
});

Proxies or caches IdP metadata for the client (authority discovery).

Type: AuthOidcWellKnownApiConfig.

Portal examples

File	Handler
`src/pages/api/auth/session.ts`	`createAuthSessionHandler` + portal BFF
`src/pages/api/auth/logout.ts`	`createAuthLogoutHandler`
`src/pages/api/auth/oidc-well-known.ts`	`createAuthOidcWellKnownHandler`

Security checklist

Validate request body on POST (tokens required, types string).
Never return refresh tokens in JSON responses.
Use cookies helpers for all Set-Cookie headers.
Keep AUTH_SESSION_SECRET server-only.

See Auth integration for full portal setup.

API route handlers

Session — createAuthSessionHandler