---
title: "useAuth"
description: "useAuth, auto-imported in the app: its options, return value and types."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/use-auth"
---
# useAuth

## Interfaces

### UseBackendAuthService

Defined in: [src/runtime/vue/composables/use-auth.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts)

The backend identity service: the base Convex + Better Auth service
extended with this package's passwordless flows and authorization reads.

#### Extends

- `UseBetterAuthReturn`

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Inherited from
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="signout">
        
      </a>
      
       <code>
        signOut
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Sign the current user out.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="sendotp">
        
      </a>
      
       <code>
        sendOtp
      </code>
    </td>
    
    <td>
      (<code>
        email
      </code>
      
      , <code>
        type?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Send a sign-in / verification OTP code to an email. <code>
        'forget-password'
      </code>
      
       answers 400 unless the app turned on <code>
        emailAndPassword
      </code>
      
      .
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="signinwithotp">
        
      </a>
      
       <code>
        signInWithOtp
      </code>
    </td>
    
    <td>
      (<code>
        args
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Complete sign-in (or passwordless sign-up) with an emailed OTP code.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="signinwithpasskey">
        
      </a>
      
       <code>
        signInWithPasskey
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Sign in with a passkey (WebAuthn).
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="registerpasskey">
        
      </a>
      
       <code>
        registerPasskey
      </code>
    </td>
    
    <td>
      (<code>
        context?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Register a passkey for the signed-in user.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="updateuser">
        
      </a>
      
       <code>
        updateUser
      </code>
    </td>
    
    <td>
      (<code>
        args
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Update profile fields (name / avatar image) on the current user.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="deleteaccount">
        
      </a>
      
       <code>
        deleteAccount
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        unknown
      </code>
      
      >
    </td>
    
    <td>
      Delete the account (confirmed via email). To change the email address, use <code>
        useEmailChange
      </code>
      
      .
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="role">
        
      </a>
      
       <code>
        role
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      The app-wide role; <code>
        'user'
      </code>
      
       when signed out or unset.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="hasrole">
        
      </a>
      
       <code>
        hasRole
      </code>
    </td>
    
    <td>
      (<code>
        role
      </code>
      
      ) => <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether the user has (any of) the given app-wide role(s).
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="can">
        
      </a>
      
       <code>
        can
      </code>
    </td>
    
    <td>
      (<code>
        permissions
      </code>
      
      ) => <code>
        boolean
      </code>
    </td>
    
    <td>
      Check permission statements (e.g. <code>
        { user: ['ban'] }
      </code>
      
      ) against the user's role — sync and local.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="banned">
        
      </a>
      
       <code>
        banned
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      Whether the account is banned.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts" rel="nofollow">
        src/runtime/vue/composables/use-auth.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isloading">
        
      </a>
      
       <code>
        isLoading
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       until the session is known and no prefetched token covers the gap.
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.isLoading
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isauthenticated">
        
      </a>
      
       <code>
        isAuthenticated
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       when Better Auth reports a session, or a token is cached while it reloads.
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.isAuthenticated
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="fetchaccesstoken">
        
      </a>
      
       <code>
        fetchAccessToken
      </code>
    </td>
    
    <td>
      <code>
        AuthTokenFetcher
      </code>
    </td>
    
    <td>
      Convex's token fetcher: the Better Auth JWT for the current session, or <code>
        null
      </code>
      
      .
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.fetchAccessToken
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="client">
        
      </a>
      
       <code>
        client
      </code>
    </td>
    
    <td>
      <code>
        AuthClient
      </code>
    </td>
    
    <td>
      The Better Auth client from <code>
        #convex/auth-client
      </code>
      
       — sign-in, sign-out and every plugin flow live here.
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.client
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="session">
        
      </a>
      
       <code>
        session
      </code>
    </td>
    
    <td>
      <code>
        unknown
      </code>
    </td>
    
    <td>
      Better Auth's own <code>
        useSession()
      </code>
      
       ref: <code>
        { data, isPending, error }
      </code>
      
      .
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.session
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="user">
        
      </a>
      
       <code>
        user
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        BetterAuthUser
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      The current user, or <code>
        null
      </code>
      
       when signed out / still loading.
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.user
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="authversion">
        
      </a>
      
       <code>
        authVersion
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      The session id (or user id); changes when the signed-in identity changes.
    </td>
    
    <td>
      <code>
        UseBetterAuthReturn.authVersion
      </code>
    </td>
    
    <td>
      node_modules/nuxt-convex-module/runtime/better-auth/vue/use-better-auth
    </td>
  </tr>
</tbody>
</table>

## Functions

### useAuth()

```ts
function useAuth(initialToken?): UseBackendAuthService;
```

Defined in: [src/runtime/vue/composables/use-auth.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-auth.ts)

The backend identity composable — the base Better Auth service
(`isLoading`, `isAuthenticated`, `fetchAccessToken`, `client`, `session`,
`user`, `authVersion`) extended with the passwordless flows and
authorization reads this package is opinionated about. Everything else
(admin/organization management, …) lives on the fully-typed `client`.

The base module registers its service as `useBetterAuth`; this is the only
`useAuth` auto-import in apps using `nuxt-backend`.

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        initialToken?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
      
       | <code>
        null
      </code>
    </td>
    
    <td>
      Optional preloaded token (SSR), forwarded to the base.
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`UseBackendAuthService`](#usebackendauthservice)


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.