the default Nuxt module export
a named magic-sso-auth route middleware
/verify-email, POST /verify-email/otp, and POST-only /logout server routes
app composables such as useMagicSsoAuth() and useMagicSsoConfig()
server utilities exposed from @magic-link-sso/nuxt/server

Server helpers such as buildLoginUrl(event, pathname, scope?) can forward an optional requested scope, verified auth payloads expose email, scope, and siteId, and direct verifyAuthToken() calls now require explicit expectedAudience and expectedIssuer values.

Required Runtime Config / Environment

At minimum, configure:

MAGICSSO_SERVER_URL=http://localhost:3000
MAGICSSO_JWT_SECRET=replace-me-with-a-long-random-jwt-secret
MAGICSSO_PREVIEW_SECRET=replace-me-with-a-different-long-random-preview-secret
MAGICSSO_COOKIE_NAME=magic-sso

Optional:

MAGICSSO_COOKIE_PATH=/
MAGICSSO_COOKIE_MAX_AGE=3600
MAGICSSO_DIRECT_USE=false
MAGICSSO_PUBLIC_ORIGIN=https://app.example.com
MAGICSSO_TRUST_PROXY=false

Variable	Required	Default	Notes
`MAGICSSO_COOKIE_NAME`	Effectively yes	`token` in module defaults	Set this explicitly to match the server cookie name. The Nuxt `/logout` route uses it too.
`MAGICSSO_COOKIE_PATH`	No	`/`	Optional path scope for the Nuxt-managed auth cookie. Narrowing it can make auth unavailable outside that subtree.
`MAGICSSO_COOKIE_MAX_AGE`	No	Session cookie	Optional persistent cookie lifetime in seconds for the Nuxt-managed auth cookie. Set it to match or stay below the server JWT expiration.
`MAGICSSO_DIRECT_USE`	No	`false`	When `true`, the Nuxt auth middleware redirects straight to the SSO server instead of the local `/login` page. `1`, `yes`, and `on` are also treated as enabled.
`MAGICSSO_JWT_SECRET`	Yes for protected routes	None	Used by SSR route middleware and server helpers to verify the auth JWT. Must match the server JWT secret.
`MAGICSSO_PREVIEW_SECRET`	Yes for local callback	None	Used by the built-in `/verify-email` route to preview the email token before exchange. Must match the server preview secret.
`MAGICSSO_PUBLIC_ORIGIN`	Recommended	None	Explicit app origin used for site-bound JWT audience checks. Set this in direct deployments so auth verification does not depend on request headers.
`MAGICSSO_SERVER_URL`	Yes	None	Base URL of the SSO server used by the local sign-in API route, `/verify-email` callback, and issuer validation for site-bound auth tokens.
`MAGICSSO_TRUST_PROXY`	No	`false`	Only enable this behind a trusted proxy that sanitizes `X-Forwarded-*` headers. When `false`, auth verification requires `MAGICSSO_PUBLIC_ORIGIN`.

Auth tokens are site-bound. Upgrading to this release invalidates older session cookies that were issued without siteId/aud/iss, so users need to sign in again after deployment.

Basic Usage

Register the module

export default defineNuxtConfig({
    modules: ['@magic-link-sso/nuxt'],
});

Protect a page

<script setup lang="ts">
definePageMeta({
    middleware: ['magic-sso-auth'],
});

const auth = useState('auth', () => null);

if (import.meta.server) {
    auth.value = await useMagicSsoAuth();
}
</script>

Customize excluded public paths

export default defineNuxtConfig({
    modules: ['@magic-link-sso/nuxt'],
    runtimeConfig: {
        magicSso: {
            excludedPaths: ['/healthz', '/docs'],
        },
    },
});

Use server utilities directly

import {
    getMagicSsoConfig,
    verifyRequestAuth,
} from '@magic-link-sso/nuxt/server';

export default defineEventHandler(async (event) => {
    const auth = await verifyRequestAuth(event);
    return {
        auth,
        config: getMagicSsoConfig(event),
    };
});

Verify a token directly

import { verifyAuthToken } from '@magic-link-sso/nuxt/server';

const auth = await verifyAuthToken(token, secret, {
    expectedAudience: 'https://app.example.com',
    expectedIssuer: 'https://sso.example.com',
});

Exchange an email OTP

The module installs POST /verify-email/otp for app-owned sign-in forms. Send challengeId and code to that local route; it exchanges and validates the access token server-side before setting the HTTP-only auth cookie.