Cookie Authentication

Overview

Nuxt-Umbu provides first-class support for Laravel Sanctum SPA authentication using secure HTTP-only cookies and CSRF protection.

This is the recommended authentication strategy when your Nuxt and Laravel applications share the same top-level domain.

Official Laravel documentation: SPA Authentication

How Cookie Authentication Works

When using the Sanctum provider, Nuxt-Umbu automatically handles:

• CSRF cookie retrieval (/sanctum/csrf-cookie)
• Sending the X-XSRF-TOKEN header
• Managing HTTP-only session cookies
• Forwarding cookies and headers between CSR and SSR
• Authentication state handling

Authentication Flow

1. User submits credentials to the configured endpoints.login
2. Nuxt-Umbu ensures a CSRF cookie is retrieved
3. Laravel authenticates the user and sets a session cookie
4. All subsequent requests automatically include:
   • Session cookie
   • X-XSRF-TOKEN header
5. The promise resolves on success or rejects on error
6. The developer must handle redirection manually

Example using .then() / .catch()

const { $auth } = useNuxtApp()

const form = ref({
    email: '',
    password: ''
})

const submit = () => {
    $auth.loginWith('sanctum', form.value)
        .then((response) => {
            // authentication successful
            navigateTo('/dashboard')
        })
        .catch((error) => {
            // handle validation or authentication errors
            console.error(error)
        })
}

CSRF Handling

By default, Nuxt-Umbu follows Laravel Sanctum's standard CSRF naming conventions.

Currently, these values are fixed and not configurable:

The module automatically:

• Extracts the XSRF-TOKEN cookie from the server response
• Sends its value in the X-XSRF-TOKEN header on subsequent requests
• Ensures CSRF protection works in both CSR and SSR environments

These defaults match Laravel Sanctum's expected behavior and require no additional configuration.

Note: Future versions of Nuxt-Umbu may allow customization of CSRF cookie and header names.

Laravel configuration

Your Laravel API should be configured properly to support Nuxt domain and share cookies:

• The Nuxt application domain should be registered in stateful domain list (SANCTUM_STATEFUL_DOMAINS)
• The Nuxt application domain should be registered in config/cors.php in allowed_origins domain list
• Also config/cors.php configuration should have support_credentials=true
• Sanctum statefulApi middleware should be enabled
• The top-level domain should be used for the session (SESSION_DOMAIN=.domain.com), or localhost during development (without port)

If you notice incorrect behavior of the module or authentication flow, feel free to raise an issue!