Protect path surfaces
Protect path surfaces
protectedPaths is plugin-owned. It is the place for your app routes (/admin, /portal), not Nile's generated auth URLs.
SDK routes (SIGNIN, CSRF, ME, …) only remaps nile-auth endpoints. Putting ME: "/admin" would steal identity onto the admin app.
Configure the three surfaces
protectedPaths: [
{ prefix: "/admin", access: "platform" },
{ prefix: "/portal", access: "session" },
{ prefix: "/affiliates", access: "tenant" },
],
excludedPaths: ["/portal/health"],
superAdmins: ["ops@example.com"],
access | Prefix | Checks |
|---|---|---|
platform | /admin | Session + superAdmins allowlist (id or email). No tenant required |
session | /portal | Session only |
tenant | /affiliates | Session + tenant id (URL param / header / cookie) |
prefix is a directory guard: /admin and /admin/stats match. Matching is boundary-aware — /admin does not match /administrator or /admin-extra (unlike xAuthBetter startsWith).
Add the platform entry only when superAdmins is a non-empty array. Registration throws if access: "platform" is set with an empty allowlist.
Skip public children
excludedPaths: ["/portal/health"]
Per-entry excludedPaths override the instance list. Mounted Nile routes (/api/auth/*, /api/me, …) are always skipped so CSRF stays public.
Guard a single route
Routes outside these prefixes use preHandlers:
const auth = fastify.xAuthNile.default;
fastify.get("/internal/stats", {
preHandler: [auth.requireAuth(), auth.requireSuperAdmin()],
}, async (request) => ({ user: request.user }));
Legacy prefix: "/api" is session-only shorthand for a single surface. Prefer protectedPaths when you have /admin and /portal.
routePrefix (e.g. /portal or /admin when routePrefix is /api), configure cookiePath: "/" in instance options so browsers send Nile session cookies to both /api and out-of-prefix routes without requiring proxy-level cookie rewrites.See also
AI Context
package: "@xenterprises/fastify-xauth-nile"
method: configs[].protectedPaths
use-when: guard Fastify app prefixes — /admin platform, /portal session, /affiliates tenant; not for remapping /api/auth/csrf
usage: protectedPaths: [{ prefix: '/admin', access: 'platform' }, { prefix: '/portal', access: 'session' }]