API & Composable Reference

import { useBearerAuth, useAuth } from '#imports'

const auth = useBearerAuth<CustomUser>()

// 1. Login with credentials
login(credentials: LoginCredentials, redirectPath?: string | null): Promise<AuthApiResponse<User>>

// 2. Social login with OAuth provider JWT/Token
socialLogin(credentials: SocialLoginCredentials, redirectPath?: string | null): Promise<AuthApiResponse<User>>

// 3. Register a new user
register(payload: Record<string, unknown>, redirectPath?: string | null): Promise<AuthApiResponse<User>>

// 4. Verify OTP code
verifyOtp(payload: Record<string, unknown>, redirectPath?: string | null): Promise<AuthApiResponse<User>>

// 5. Fetch current user from /api/auth/me
fetchUser(options?: FetchUserOptions): Promise<{ data: User | null; error: string | null }>

// 6. Silent token refresh
refresh(): Promise<AuthApiResponse<User>>

// 7. Logout and destroy session
logout(destination?: string): Promise<void>

// 8. Forgot password request
forgotPassword(payload: Record<string, unknown>): Promise<any>

// 9. Reset password request
resetPassword(payload: Record<string, unknown>): Promise<any>

// 10. Resend OTP code
resendOtp(identifier: string, payload?: Record<string, unknown>): Promise<any>

// 11. Clear client auth state manually
clearAuthState(): void

// 12. Advisory ability check — exact string match against auth.abilities
can(ability: string): boolean

// 13. Inverse of can()
cannot(ability: string): boolean

import {
  // Session read/write
  getBearerAuthSession,       // Read session from Redis by cookie
  createBearerAuthSession,    // Create new session after authentication
  updateBearerAuthSession,    // Update token, refreshToken, or profile in session
  destroyBearerAuthSession,   // Delete session from Redis and clear cookie
  destroyAllBearerAuthSessions, // Delete all sessions for a user ID
  getUserBearerAuthSessions,  // List PublicSession[] for a user (no tokens)
  deleteUserBearerAuthSession, // Delete a specific session with ownership check

  // Guard utility
  requireBearerAuthSession,   // Read event.context.auth or throw 401

  // External API proxy
  callAuthApi,                // Make authenticated request to backend using session token

  // Redis client (advanced use)
  getBearerAuthRedisClient,
} from '#imports'

<Can ability="users.delete">
  <button>Delete user</button>

  <template #fallback>
    <span>You do not have permission to delete users.</span>
  </template>
</Can>

export type AuthStatus = 'idle' | 'loading' | 'authenticated' | 'unauthenticated'

export interface BearerAuthUser {
  id?: string | number
  uuid?: string
  email?: string
  name?: string
  [key: string]: unknown  // Open-ended — your backend user shape
}

export interface BearerAuthSession<User extends BearerAuthUser = BearerAuthUser> {
  userId: string
  token: string           // Bearer token — server-side only
  refreshToken?: string | null
  profile: User | null
  createdAt: string       // ISO timestamp
  expiresAt: number       // Epoch milliseconds (application-level expiry guard)
  lastActivity: string    // ISO timestamp — updated on each authenticated request
  userAgent?: string
  ipAddress?: string
  abilities?: string[] | null  // Normalized ability strings — server-derived
}

// Safe public shape — omits token, refreshToken, userId, expiresAt
export interface PublicSession {
  id: string
  createdAt: string
  lastActivity: string
  userAgent?: string
  ipAddress?: string
}

export interface AuthApiResponse<T = unknown> {
  success: boolean
  message?: string
  data?: T
  user?: BearerAuthUser | null
  code?: string | number
  nextAction?: string
}

export interface LoginCredentials {
  identifier?: string
  email?: string
  username?: string
  phone?: string
  mobile?: string
  password?: string
  [key: string]: unknown
}

export interface SocialLoginCredentials {
  jwt?: string
  token?: string
  provider?: string
  [key: string]: unknown
}

export interface FetchUserOptions {
  refresh?: boolean
}

import type {
  // Auth state and response types
  AuthStatus,
  AuthApiResponse,
  BearerAuthUser,
  BearerAuthSession,
  PublicSession,

  // Credential types
  LoginCredentials,
  SocialLoginCredentials,
  FetchUserOptions,

  // Module configuration types
  BearerAuthModuleOptions,
  BearerAuthEndpointOptions,
  BearerAuthResponsePaths,
  BearerAuthRedirectOptions,
  BearerAuthRouteOptions,
  BearerAuthCookieOptions,
  BearerAuthCsrfOptions,

  // Authorization types
  Ability,
  AuthorizationSource,
  AuthorizationMatchMode,
  AuthorizationRouteRequirement,
  AuthorizationResponsePaths,
  AuthorizationState,
  BearerAuthAuthorizationConfig,
} from 'nuxt-bearer-auth'

// Example: extending BearerAuthUser with your own fields
import type { BearerAuthUser } from 'nuxt-bearer-auth'

interface AppUser extends BearerAuthUser {
  role: 'admin' | 'editor' | 'viewer'
  organizationId: string
  avatarUrl?: string
}

// Pass your type to the composable for full type inference
const auth = useBearerAuth<AppUser>()

// auth.user.value is now typed as AppUser | null
console.log(auth.user.value?.role)

# In the nuxt-bearer-auth package directory
npm test