All authentication endpoints and configuration options.
All auth endpoints are mounted under /__nk_auth/:
| Route | Method | Body | Response |
|---|---|---|---|
/__nk_auth/login | GET | -- | Redirects to OIDC provider, or returns JSON list of providers |
/__nk_auth/login/:provider | GET | -- | Redirects to specific OIDC provider |
/__nk_auth/login | POST | { email, password } | Native login. Returns user + sets session cookie (or bearer tokens with ?mode=token) |
/__nk_auth/signup | POST | { email, password, name? } | Native registration. Returns user (201) |
/__nk_auth/callback | GET | -- | OIDC code exchange callback. Sets session cookie, redirects to returnTo |
/__nk_auth/logout | GET | -- | Clears session. Redirects to OIDC end-session endpoint if applicable |
/__nk_auth/me | GET | -- | Returns current user JSON or null |
/__nk_auth/verify-email | GET | ?token=... | Marks email as verified, redirects to login page |
/__nk_auth/forgot-password | POST | { email } | Sends password reset link (if email exists) |
/__nk_auth/reset-password | POST | { token, password } | Resets password using token |
/__nk_auth/refresh | POST | { refreshToken } | Rotates tokens. Returns new accessToken + refreshToken |
/__nk_auth/revoke | POST | { refreshToken } | Invalidates a refresh token. Returns { ok: true } |
Full lumenjs.auth.ts options:
| Option | Type | Default | Description |
|---|---|---|---|
providers | AuthProvider[] | -- | Array of auth providers (native and/or OIDC). Required. |
providers[].type | 'native' | 'oidc' | -- | Provider type |
providers[].name | string | -- | Unique provider name (used in URLs and session data) |
providers[].issuer | string | -- | OIDC issuer URL (OIDC only) |
providers[].clientId | string | -- | OIDC client ID (OIDC only) |
providers[].clientSecret | string? | -- | OIDC client secret (OIDC only, optional for public clients) |
providers[].scopes | string[]? | ['openid', 'profile', 'email'] | OIDC scopes to request |
providers[].minPasswordLength | number? | 8 | Minimum password length (native only) |
providers[].allowRegistration | boolean? | true | Allow public user registration (native only) |
providers[].requireEmailVerification | boolean? | false | Require email verification before login (native only) |
session.secret | string | -- | Encryption key for session cookies and tokens. Required. |
session.cookieName | string? | 'nk-session' | Session cookie name |
session.maxAge | number? | 604800 | Session TTL in seconds (7 days) |
session.secure | boolean? | false | Set Secure flag on cookies (use true in production) |
routes.login | string? | '/__nk_auth/login' | Login API route |
routes.loginPage | string? | '/auth/login' | Login UI page (where guards redirect to) |
routes.callback | string? | '/__nk_auth/callback' | OIDC callback route |
routes.logout | string? | '/__nk_auth/logout' | Logout route |
routes.signup | string? | '/__nk_auth/signup' | Signup route (native auth) |
routes.postLogin | string? | '/' | Redirect after successful login |
routes.postLogout | string? | '/' | Redirect after logout |
guards.defaultAuth | boolean? | false | Require auth on all pages by default |
token.enabled | boolean? | true | Enable bearer token mode (?mode=token) |
token.accessTokenTTL | number? | 900 | Access token TTL in seconds (15 min) |
token.refreshTokenTTL | number? | 604800 | Refresh token TTL in seconds (7 days) |
onEvent | (event) => void | -- | Hook for auth events: verification-email, password-reset, password-changed |