Pure Surreal Database Authentication in Nuxt

See how Nuxt pairs up with Surreal Database with a sample app enabling login, register, logout and password change options with route guards and server-safe APIs.

I am obsessed with Surreal Database. I love graph databases, and this database allows us to avoid joins forever!

TL;DR

This app allows you to connect to Surreal Database and use the first class login system with Nuxt 4. You can login, register, logout and change your password with route guards and server-safe APIs.

Surreal Database Setup

First, set up a cloud instance with Surreal Cloud. This example should also work with a local version.

📝 I’m using Surreal 2.3.10 or later.

Schema

We must declare our Surreal Schema with sign in and sign up functions.

-- 🔐 ACCESS RULE
DEFINE ACCESS user
    ON DATABASE
    TYPE RECORD
    SIGNUP (
        CREATE users SET
            username = $username,
            password = crypto::argon2::generate($password)
    )
    SIGNIN (
        SELECT * FROM users
        WHERE username = $username
          AND crypto::argon2::compare(password, $password)
    )
    WITH JWT
        ALGORITHM HS512
        KEY 'YOUR_SUPER_SECRET_KEY_HERE'
        DURATION
            FOR TOKEN 1h,
            FOR SESSION NONE;

-- 👤 USERS TABLE
DEFINE TABLE users
    TYPE NORMAL
    SCHEMAFULL
    PERMISSIONS
        FOR select, update WHERE id = $auth.id,
        FOR create, delete NONE;

-- 🧩 FIELD DEFINITIONS
DEFINE FIELD username
    ON users
    TYPE string
    ASSERT $value != ''
    PERMISSIONS FULL;

DEFINE FIELD password
    ON users
    TYPE string
    ASSERT $value != ''
    PERMISSIONS FULL;

-- 🔎 UNIQUE INDEX
DEFINE INDEX usernameIndex
    ON TABLE users
    COLUMNS username
    UNIQUE;

• SIGNIN and SIGNUP functions must be declared and will store the username and encrypted password in the database.
• We use users, but user could work as well, depending on your preference.
• Currently, for proper permissions, you need a SCHEMAFULL table declared. I also added a usernameIndex, which also enables uniqueness.

🔓 Currently Surreal ONLY supports the before state in an update statement, so this could be a HUGE security risk. I have created an issue for it. You could work around this with a trigger function.

Surreal JS

Install the latest version. We are still in alpha here.

npm i surrealdb@alpha

Basic Nuxt Setup

I just created a blank Nuxt app and installed Tailwind.

npm create nuxt@latest

I didn’t use the package, but vanilla Tailwind installation.

Environment Variables

Put your database info in the .env file for easy access. You don’t want to push this up to GitHub, although it wouldn’t be the worst thing.

NUXT_SURREAL_URL=...
NUXT_SURREAL_NAMESPACE=...
NUXT_SURREAL_DATABASE=...

The NUXT_ prefix allows us to use the variables anywhere on the server.

nuxt.config.ts

We can add placeholders here that will automatically import the variables.

import tailwindcss from "@tailwindcss/vite"

// <https://nuxt.com/docs/api/configuration/nuxt-config>
export default defineNuxtConfig({
  compatibilityDate: '2025-07-15',
  devtools: { enabled: true },
  css: ['./app/assets/css/main.css'],
  vite: {
    plugins: [
      tailwindcss()
    ]
  },
  runtimeConfig: {
    surrealDatabase: '',
    surrealNamespace: '',
    surrealUrl: ''
  }
})

Surreal Functions

We must create a server instance.

Create a Server

export async function createSurrealServer(event: H3Event) {

    const config = useRuntimeConfig()

    const db = new Surreal()

    try {
        await db.connect(config.surrealUrl, {
            namespace: config.surrealNamespace,
            database: config.surrealDatabase
        })
    } catch (error) {
        if (error instanceof Error) {
            console.error(error)
            return {
                error,
                data: null
            }
        }
        return {
            error: new Error('Unknown connection error'),
            data: null
        }
    }

    const surrealToken = getCookie(
        event,
        SURREAL_COOKIE_NAME
    )

    if (surrealToken) {
        await db.authenticate(surrealToken)
    }

    return {
        data: db,
        error: null
    }
}

• We get the useRuntimeConfig() for our database variables to connect.
• Unfortunately, we have to use try / catch for error handling, but I’m hoping to get this fixed with Supabase-like error destructuring.
• We create an class instance with Surreal().
• We connect with db.connect(). However, if we’re using http version, this just setups up our REST call.
• Surreal is 100% compatible outside of Node.js with an HTTP version. We just don’t use wss:// and replace it with http:// version of our URL. This is huge for Edge Computing, Bun, Deno, Cloudflare and any other V8 Isolates.
• We check for a token, and if there is one, add it to the next authentication header with db.authenticate().

Login and Register

The login and register functions are nearly identical.

export async function surrealLogin(event: H3Event, username: string, password: string) {

    const config = useRuntimeConfig()

    const { data: db, error: dbError } = await createSurrealServer(event)

    if (dbError) {
        if (dbError instanceof Error) {
            console.error(dbError)
            return {
                error: dbError,
                data: null
            }
        }
        return {
            error: new Error('Unknown login error'),
            data: null
        }
    }

    if (!db) {
        return {
            data: null,
            error: new Error("No SurrealDB instance")
        }
    }

    try {
        const auth = await db.signin({
            namespace: config.namespace,
            database: config.database,
            variables: {
                username,
                password
            },
            access: 'user'
        })

        const { token } = auth

        setCookie(
            event,
            SURREAL_COOKIE_NAME,
            token,
            COOKIE_OPTIONS
        )

        return {
            data: token,
            error: null
        }

    } catch (signInError) {

        surrealLogout(event)

        if (signInError instanceof Error) {
            console.error(signInError)
            return {
                error: signInError,
                data: null
            }
        }
        return {
            error: new Error('Unknown sign-in error'),
            data: null
        }
    }
}

export async function surrealRegister(event: H3Event, username: string, password: string) {

    const config = useRuntimeConfig()

    const { data: db, error: dbError } = await createSurrealServer(event)

    if (dbError) {
        return {
            data: null,
            error: dbError
        }
    }

    if (!db) {
        return {
            data: null,
            error: new Error("No SurrealDB instance")
        }
    }

    try {
        const auth = await db.signup({
            namespace: config.namespace,
            database: config.database,
            variables: {
                username,
                password
            },
            access: 'user'
        })

        const { token } = auth

        setCookie(
            event,
            SURREAL_COOKIE_NAME,
            token,
            COOKIE_OPTIONS
        )

        return {
            data: token,
            error: null
        }

    } catch (signUpError) {

        surrealLogout(event)

        if (signUpError instanceof Error) {
            console.error(signUpError)
            return {
                error: signUpError,
                data: null
            }
        }
        return {
            error: new Error('Unknown sign-up error'),
            data: null
        }
    }
}

• We get our server instance with our createSurrealServer() function.
• We configure our login:

{
    namespace: config.namespace,
    database: config.database,
    variables: {
        username,
        password
    },
    access: 'user'
}

This must match our configuration.

• We set the cookie and return the token.
• Same code for signin and signup.

Logout

We just delete the cookie.

export function surrealLogout(event: H3Event) {

    deleteCookie(
        event,
        SURREAL_COOKIE_NAME,
        COOKIE_OPTIONS
    )
}

Change Password

We need to be able to change our password.

export async function surrealChangePassword(
    event: H3Event,
    currentPassword: string,
    newPassword: string
) {

    const { data: db, error: dbError } = await createSurrealServer(event)

    if (dbError) {
        return {
            data: null,
            error: dbError
        }
    }

    if (!db) {
        return {
            data: null,
            error: new Error("No SurrealDB instance")
        }
    }

    try {

        const { data: userId } = await getCurrentUserId(event)

        if (!userId) {
            return {
                data: null,
                error: null
            }
        }

        const query = `
            UPDATE $id
            SET password = crypto::argon2::generate($new)
            WHERE crypto::argon2::compare(password, $old)
        `

        const [result] = await db.query(query, {
            id: new RecordId('users', userId),
            old: currentPassword,
            new: newPassword
        }).collect<[{ id: string, password: string, username: string }][]>()

        if (!result) {
            return {
                data: null,
                error: new Error("Password change failed")
            }
        }
        return {
            data: result[0],
            error: null
        }
    } catch (error) {
        if (error instanceof Error) {
            console.error(error)
            return {
                error,
                data: null
            }
        }
        return {
            error: new Error('Unknown query error'),
            data: null
        }
    }
}

• Our query updates the password where the current password and current user ID are equal.
• We use db.query() to query the database and safely pass in our id, old password and new password.
• The collect() method helps us get the typing right. I will return an array with an array.
• We use a RecordId instance to handle our users:0001 id query.

📝 There will be a db.select() function in the future, but it will not handle advanced queries yet, so I didn’t include it.

Get Current User ID

We need to get the user ID from our cookie token, or from the database itself.

export async function getCurrentUserId(event: H3Event, refetch = false) {

    const token = getCookie(event, SURREAL_COOKIE_NAME)

    if (!token) {
        return {
            data: null,
            error: null
        }
    }

    if (refetch) {

        const {
            data: db,
            error: dbError
        } = await createSurrealServer(event)

        if (dbError) {
            return {
                data: null,
                error: dbError
            }
        }

        if (!db) {
            return {
                data: null,
                error: new Error("No SurrealDB instance")
            }
        }

        try {
            const userId = (await db.auth())?.id.id.toString()

            if (!userId) {
                return {
                    data: null,
                    error: null
                }
            }
            return {
                data: userId,
                error: null
            }

        } catch (error) {
            if (error instanceof Error) {
                console.error(error)
                return {
                    error,
                    data: null
                }
            }
            return {
                error: new Error('Unknown authentication error'),
                data: null
            }
        }
    }

    const userId = parseToken(token)

    return {
        data: userId,
        error: null
    }
}

• We can fetch the logged-in user directly from the database with db.auth() for the safest route. This is imperative for critical operations like password changes, deleting and certain updates.

However, to save us an extraneous database call for most non-critical operations, the cookie will suffice.

export function parseToken(token: string) {
    return JSON.parse(atob(token.split('.')[1])).ID.split(':')[1] as string
}

Nuxt Server APIs

Next, we must create our Nuxt Endpoints to handle the Surreal data.

Login / Redirect

// server/api/login.post.ts

import { parseToken, surrealLogin } from "../utils/surreal"

export default defineEventHandler(async (event) => {

    const body = await readBody<{
        username: string
        password: string
    }>(event)

    const { username, password } = body

    if (!username || !password) {
        throw createError({
            statusCode: 400,
            message: 'Missing credentials'
        })
    }

    const {
        data: token,
        error: loginError
    } = await surrealLogin(event, username, password)

    if (loginError) {
        throw createError({
            statusCode: 500,
            message: 'Login failed',
            data: loginError.message
        })
    }

    if (!token) {
        throw createError({
            statusCode: 401,
            message: 'Invalid credentials',
            data: token
        })
    }

    const userId = parseToken(token)

    if (!userId) {
        throw createError({
            statusCode: 401,
            message: 'Unauthorized',
            data: userId
        })
    }

    sendRedirect(event, '/')
})

// server/api/register.post.ts

import { parseToken, surrealRegister } from "../utils/surreal"

export default defineEventHandler(async (event) => {

    const body = await readBody<{
        username: string
        password: string
    }>(event)

    const { username, password } = body

    if (!username || !password) {
        throw createError({
            statusCode: 400,
            message: 'Missing credentials'
        })
    }

    const {
        data: token,
        error: registerError
    } = await surrealRegister(event, username, password)

    if (registerError) {
        throw createError({
            statusCode: 500,
            message: 'Registration failed',
            data: registerError.message
        })
    }

    if (!token) {
        throw createError({
            statusCode: 401,
            message: 'Invalid credentials',
            data: token
        })
    }

    const userId = parseToken(token)

    if (!userId) {
        throw createError({
            statusCode: 401,
            message: 'Unauthorized',
            data: userId
        })
    }

    sendRedirect(event, '/')
})

• We get our data from readBody and error out with createError.
• A successful login redirects home with sendRedirect.
• We add .post.ts to the end so that it gets called correctly.
• Again, both register and login are very similar.

Logout

Nothing to this but calling our logout function and redirecting.

// server/api/logout.get.ts

import { surrealLogout } from "../utils/surreal"

export default defineEventHandler((event) => {
    surrealLogout(event)
    sendRedirect(event, "/")
})

Password

You can start to see the pattern of calling our functions.

// server/api/password.post.ts

import { surrealChangePassword } from "../utils/surreal"

export default defineEventHandler(async (event) => {

    const body = await readBody<{
        current_password: string
        new_password: string
    }>(event)

    const { current_password, new_password } = body

    if (!current_password || !new_password) {
        throw createError({
            statusCode: 400,
            message: 'Missing credentials'
        })
    }

    const {
        data: newRecord,
        error: changePasswordError
    } = await surrealChangePassword(
        event,
        current_password,
        new_password
    )

    if (changePasswordError) {
        throw createError({
            statusCode: 500,
            message: 'Change password failed',
            data: changePasswordError.message
        })
    }

    if (!newRecord?.id) {
        throw createError({
            statusCode: 401,
            message: 'Invalid credentials',
            data: newRecord
        })
    }

    sendRedirect(event, '/')
})

• Same deal. Run function, redirect.

Get User

We must get the user, or user ID, from our function to have it available on the client.

// server/api/user.get.ts

import { getCurrentUserId } from "../utils/surreal"

export default defineEventHandler(async (event) => {
    const { data: userId } = await getCurrentUserId(event)
    return { userId }
})

Middleware and Composables

We must protect our routes and get our data.

useAuth

This runs on the server and client, but fetches from the server.

// composables/useAuth.ts

export async function useAuth() {

    const { data, error } = await useFetch<{ userId: string | null }>("/api/user", {
        server: true,
        default: () => ({ userId: null }),
        lazy: false
    })

    if (error.value) {
        console.error(error.value)
    }

    const userId = computed(() => data.value?.userId || null)

    return { userId }
}

• Run on server
• Block navigation until complete
• Default to null
• Get userId signal

Guards

We must protect our routes before loaded on the client.

// middleware/authGuard.ts

export default defineNuxtRouteMiddleware(async () => {
  const { userId } = await useAuth()
  if (!userId.value) {
    return navigateTo('/login', { redirectCode: 302 })
  }
})

• Must be logged in to view page.

export default defineNuxtRouteMiddleware(async () => {
  const { userId } = await useAuth()
  if (userId.value) {
    return navigateTo('/dashboard', { redirectCode: 302 })
  }
})

• Should never see login or register if you’re signed in.

Pages in App

In Nuxt 4, we can put everything in the app folder.

Layout

We create our shared layout in app.vue.

<script setup lang="ts">
const { userId } = await useAuth()
</script>

<template>
  <main class="mt-10 flex flex-col items-center justify-center space-y-6">
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
    <nav class="flex space-x-6">
      <NuxtLink to="/">Home</NuxtLink>
      <template v-if="userId">
        <a href="/api/logout"> Logout </a>
      </template>
      <template v-else>
        <NuxtLink to="/login">Login</NuxtLink>
      </template>
      <NuxtLink to="/dashboard">Dashboard</NuxtLink>
    </nav>
  </main>
</template>

• NuxtPage is our slot.
• NuxtLink makes sure we use our router.
• NuxtLayout decides where it goes.

Register and Login

Our register and login pages just display a form and our route guard.

// app/pages/register.vue

<script setup lang="ts">
definePageMeta({
  middleware: "guest-guard"
})
</script>

<template>
  <section>
    <h1 class="text-2xl font-bold">Register</h1>

    <form
      class="mt-10 flex flex-col items-center justify-center space-y-6"
      action="/api/register"
      method="POST"
    >
      <input
        class="rounded-lg border p-3"
        placeholder="Username"
        name="username"
        type="text"
        readonly
        onfocus="this.removeAttribute('readonly')"
      />
      <input
        class="rounded-lg border p-3"
        placeholder="Password"
        name="password"
        type="password"
        readonly
        onfocus="this.removeAttribute('readonly')"
      />
      <button class="rounded-lg border bg-blue-500 p-3 text-white">
        Register
      </button>
    </form>
    <hr class="my-5" />
    <p class="text-center text-gray-600">
      <NuxtLink to="/login" class="text-blue-500 underline">
        Already registered?
      </NuxtLink>
    </p>
    <hr class="my-5" />
  </section>
</template>

// app/pages/login.vue

<script setup lang="ts">
definePageMeta({
  middleware: "guest-guard"
})
</script>

<template>
  <section>
    <h1 class="text-2xl font-bold">Login</h1>

    <form
      class="mt-10 flex flex-col items-center justify-center space-y-6"
      action="/api/login"
      method="POST"
      autocomplete="off"
    >
      <input
        class="rounded-lg border p-3"
        placeholder="Username"
        name="username"
        type="text"
        readonly
        onfocus="this.removeAttribute('readonly')"
      />
      <input
        class="rounded-lg border p-3"
        placeholder="Password"
        name="password"
        type="password"
        readonly
        onfocus="this.removeAttribute('readonly')"
      />
      <button class="rounded-lg border bg-blue-500 p-3 text-white">
        Login
      </button>
    </form>
    <hr class="my-5" />
    <p class="text-center text-gray-600">
      <NuxtLink to="/register" class="text-blue-500 underline">
        New User?
      </NuxtLink>
    </p>
    <hr class="my-5" />
  </section>
</template>

• definePageMeta helps us declare a route guard and runs first on the server.

Change Password

Just another form with opposite route guard.

<script setup lang="ts">
definePageMeta({
  middleware: "auth-guard",
})
</script>

<template>
  <section>
    <h1 class="text-2xl font-bold">Change Password</h1>

    <form
      class="mt-10 flex flex-col items-center justify-center space-y-6"
      action="/api/password"
      method="POST"
    >
      <input
        class="rounded-lg border p-3"
        placeholder="Current Password"
        name="current_password"
        type="password"
        readonly
        onfocus="this.removeAttribute('readonly')"
      />
      <input
        class="rounded-lg border p-3"
        placeholder="New Password"
        name="new_password"
        type="password"
        readonly
        onfocus="this.removeAttribute('readonly')"
      />
      <button class="rounded-lg border bg-blue-500 p-3 text-white">
        Change Password
      </button>
    </form>
  </section>
</template>

Dashboard

Our dashboard page can only be viewed when logged in, shows the user, and links to the change password page.

<script setup lang="ts">
definePageMeta({
  middleware: ["auth-guard"]
})
const { userId } = await useAuth()
</script>

<template>
  <section class="space-y-6">
    <h1 class="text-2xl font-bold">Dashboard</h1>
    <p>This will be your login wall dashboard!</p>
    <p>
      Your user ID is: <span class="font-mono font-bold">{{ userId }}</span>
    </p>
    <hr class="my-5" />
    <p class="text-center text-gray-600">
      <NuxtLink to="/password" class="text-blue-500 underline">
        Change Password
      </NuxtLink>
    </p>
    <hr class="my-5" />
  </section>
</template>

📝 We can have many guards in an array if necessary.

Usage

We log in to access the dashboard, then register first.

Final Notes

📝 I did not create a demo for this, as I didn’t want to pay for a new cloud instance.

Security

The login token only lasts 30 minutes and is not 100% secure for production apps. If you have a small app where you’re not worried about a token getting stolen, this is a login method for you.

Otherwise, use Surreal in conjunction with better-auth or firebase-auth. However, it should be good for any startup application.

Error Handling

The REST API endpoints throw errors. The error handling should be handled best in the forms. I didn’t include this as this app was already getting too complex. However, I do recommend handling this in a production app.

• Nuxt UI Vue Forms
• Nuxt Form Actions

Repo: GitHub

Happy Nuxting!