Quick Start

After following the installation-steps, add @sidebase/nuxt-auth to your nuxt.config.ts and specify the provider-type you want to use:

export default defineNuxtConfig({    modules: ['@sidebase/nuxt-auth'],    auth: {        provider: {            type: 'authjs'        }    }})

export default defineNuxtConfig({    modules: ['@sidebase/nuxt-auth'],    auth: {        provider: {            type: 'local'        }    }})

export default defineNuxtConfig({    modules: ['@sidebase/nuxt-auth'],    auth: {        provider: {            type: 'refresh'        }    }})

Then continue with the provider-specific steps below.

Provider-specific Steps

Provider: authjs

After the nuxt.config.ts setup from above you have to create the authentication handler (NuxtAuthHandler) that will setup the backend and expose the API endpoints for handling all authentication-related requests and add at least one authentication provider:

// file: ~/server/api/auth/[...].tsimport { NuxtAuthHandler } from '#auth'import GithubProvider from 'next-auth/providers/github'export default NuxtAuthHandler({    providers: [        // @ts-expect-error You need to use .default here for it to work during SSR. May be fixed via Vite at some point        GithubProvider.default({           clientId: 'enter-your-client-id-here',           clientSecret: 'enter-your-client-secret-here'        })    ]})

Provider: local

The local provider does not require any additional steps, as it relies on an already existing backend. By default, the local provider will try to reach this backend using the following default-configuration.

{  auth: {    baseURL: '/api/auth',    provider: {      type: 'local',      endpoints: {        signIn: { path: '/login', method: 'post' },        signOut: { path: '/logout', method: 'post' },        signUp: { path: '/register', method: 'post' },        getSession: { path: '/session', method: 'get' }      },      token: { signInResponseTokenPointer: '/token/accessToken' },    }  }}

You can customize each endpoint to fit your needs or disable it by setting it to false. For example you may want to disable the getSession endpoint.

{  auth: {    baseURL: '/api/auth',    provider: {      type: 'local',      endpoints: {        getSession: false      }    }  }}

Sign In Example

To perform a sign in, all you need to do is calling the signIn function from useAuth composable and pass the credentials expected by your backend.

Take this example where we're using the default options and require the user to enter his email, phone, and password to login.

<script setup>  const email = ref('')  const phone = ref('')  const password = ref('')  const { signIn } = useAuth()  async function signInWithCredentials() {    // Probably you'll do some validation here before submitting to the backend    // ...    // This is the object that our backend expects for the `signIn` endpoint    const credentials = {      email: email.value      phone: phone.value      password: password.value    }    try {      // This sends a POST request to the `auth.provider.endpoints.signIn` endpoint with `credentials` as the body      await signIn(credentials)      alert('Successfully logged in!')    } catch (error) {      console.error(error)    }  }</script><template>  <div>    <h1>Enter your credentials to continue</h1>    <input v-model="email" type="email" />    <input v-model="phone" type="tel" />    <input v-model="password" type="password" />    <button @click="signInWithCredentials()" />  </div></template>

If the backend response includes a token in the path token.accessToken (specified above in the config), the user will be signed successfully.

// Backend response{  token: {    accessToken: 'eyBlaBlub'  },}

Full Example with local Provider

Have a look at this example in the nuxt-auth repository which uses Nuxt in the backend too.

• full nuxt app
  • its backend
  • its nuxt.config.ts

Provider: refresh

The refresh provider is exactly the same as the local provider except it has an additional refresh endpoint and a refreshToken object.

{  auth: {    baseURL: '/api/auth',    provider: {      type: 'refresh',      endpoints: {        signIn: { path: '/login', method: 'post' },        signOut: { path: '/logout', method: 'post' },        signUp: { path: '/register', method: 'post' },        getSession: { path: '/session', method: 'get' },        refresh: { path: '/refresh', method: 'post' }      },      token: { signInResponseTokenPointer: '/token' },      refreshToken: { signInResponseRefreshTokenPointer: '/refreshToken' },    }  }}

On a successful sign in with the default options, the value of refreshToken in the backend response will be saved and will be passed the body payload to the /api/auth/refresh endpoint when you call the useAuth().refresh method.

Full Example with refresh Provider

Have a look at this example in the nuxt-auth repository which uses Nuxt in the backend too.

• full nuxt app
  • its backend
  • its nuxt.config.ts

Finishing up

That's it! You can now use all user-related functionality, for example:

// file: e.g ~/pages/login.vueconst { status, data, signIn, signOut, refresh   } = useAuth()status.value // Session status: `unauthenticated`, `loading`, `authenticated`data.value // Session data, e.g., expiration, user.email, ...await signIn() // Sign in the userawait refresh() // Refresh the token await signOut() // Sign out the user

// file: e.g: ~/server/api/session.get.tsimport { getServerSession } from '#auth'export default eventHandler(async (event) => {   const session = await getServerSession(event)   if (!session) {      return { status: 'unauthenticated!' }   }   return { status: 'authenticated!', text: 'im protected by an in-endpoint check', session }})

To learn how to protect pages read about the application-side usage, to learn how to protect server-routes and API endpoints read about the server-side usage. You can also find more provider-specific information on these pages.