Appearance

useAuthApi Composable ​

File Information ​

  • Path: app/composables/api/useAuthApi.ts
  • Purpose: Authentication operations (login, logout, password reset, token login)
  • Category: Authentication API Composable

Overview ​

The useAuthApi composable provides functionality for all authentication-related operations including login, logout, password reset, and token-based login.

Functions ​

login ​

Authenticates user with email and password.

Signature:

typescript
login(
  email: string,
  password: string,
  workspaceUrlSlug?: string
): Promise<LoginResponse>

Parameters:

  • email: string - User email
  • password: string - User password
  • workspaceUrlSlug?: string - Optional workspace URL slug

Returns:

  • Promise<LoginResponse> - Login response with user and token

API Endpoint: POST /login (skipAuth: true)

Usage:

typescript
const { login } = useAuthApi()

try {
  const response = await login(email, password, workspaceSlug)
  // response contains user data and access_token
  // Store token via /api/auth/set-session
} catch (error) {
  // Handle login error
}

logout ​

Logs out user from backend.

Signature:

typescript
logout(token?: string | null): Promise<void>

Parameters:

  • token?: string | null - Optional auth token

Returns:

  • Promise<void> - No return value

API Endpoint: POST /logout

Usage:

typescript
const { logout } = useAuthApi()

// Logout (token is optional)
await logout(token)
// Then clear session via /api/auth/clear-session

getUser ​

Fetches user data using token.

Signature:

typescript
getUser(token: string): Promise<User>

Parameters:

  • token: string - Authentication token

Returns:

  • Promise<User> - User object

API Endpoint: GET /user (with Authorization header)

Usage:

typescript
const { getUser } = useAuthApi()

const user = await getUser(token)
// user contains full user data

loginWithToken ​

Logs in user with one-time token.

Signature:

typescript
loginWithToken(
  oneTimeToken: string,
  url?: string
): Promise<{ user: User, access_token: string }>

Parameters:

  • oneTimeToken: string - One-time login token
  • url?: string - Optional brand URL

Returns:

  • Promise<{ user: User, access_token: string }> - User and access token

API Endpoint: POST /login-with-id (skipAuth: true)

Usage:

typescript
const { loginWithToken } = useAuthApi()

const { user, access_token } = await loginWithToken(token, brandUrl)
// Store token via /api/auth/set-session

forgotPassword ​

Sends password reset email.

Signature:

typescript
forgotPassword(
  email: string,
  workspaceId: string
): Promise<void>

Parameters:

  • email: string - User email
  • workspaceId: string - Workspace ID/URL

Returns:

  • Promise<void> - No return value

API Endpoint: POST /forgot-password (skipAuth: true)

Usage:

typescript
const { forgotPassword } = useAuthApi()

await forgotPassword(email, workspaceId)
// Email sent to user

getResetPasswordDetails ​

Gets password reset details using token.

Signature:

typescript
getResetPasswordDetails(token: string): Promise<any>

Parameters:

  • token: string - Reset password token

Returns:

  • Promise<any> - Reset password details

API Endpoint: POST /reset-password-details (skipAuth: true)

Usage:

typescript
const { getResetPasswordDetails } = useAuthApi()

const details = await getResetPasswordDetails(resetToken)
// Verify token is valid

resetPassword ​

Resets user password.

Signature:

typescript
resetPassword(
  resetToken: string,
  token: string,
  password: string,
  timezone: string
): Promise<any>

Parameters:

  • resetToken: string - Reset password token
  • token: string - Additional token
  • password: string - New password
  • timezone: string - User timezone

Returns:

  • Promise<any> - Response data

API Endpoint: POST /reset-password (skipAuth: true)

Usage:

typescript
const { resetPassword } = useAuthApi()

await resetPassword(resetToken, token, newPassword, timezone)
// Password reset successful

Error Handling ​

All functions include error logging:

typescript
catch (error: any) {
  console.error('[AuthAPI] {functionName} - Error:', error)
  throw error
}

Note: logout does not throw errors - it only logs them.

Type Definitions ​

typescript
import type { User, LoginResponse } from '~/types'

Integration with API Client ​

The composable uses the global $api client:

typescript
const nuxtApp = useNuxtApp()
const $api = nuxtApp.$api

if (!$api || typeof $api !== 'function') {
  throw new Error('[useAuthApi] $api is not available. Make sure api-client plugin is loaded.')
}

Use Cases ​

Login Flow ​

typescript
const { login } = useAuthApi()

const handleLogin = async (email: string, password: string) => {
  try {
    const response = await login(email, password)
    
    // Store token in HTTP-only cookie
    await $api('/api/auth/set-session', {
      method: 'POST',
      body: {
        token: response.access_token,
        user: response.user
      }
    })
    
    // Redirect to dashboard
    await navigateTo('/dashboard')
  } catch (error) {
    // Show error message
    snackbar.showError('Login failed')
  }
}

Logout Flow ​

typescript
const { logout } = useAuthApi()

const handleLogout = async () => {
  try {
    // Logout from backend
    await logout(token)
  } catch (error) {
    // Log error but continue
  } finally {
    // Clear session cookies
    await $api('/api/auth/clear-session', {
      method: 'POST'
    })
    
    // Redirect to login
    await navigateTo('/login')
  }
}

Password Reset Flow ​

typescript
const { forgotPassword, getResetPasswordDetails, resetPassword } = useAuthApi()

// Step 1: Request reset
await forgotPassword(email, workspaceId)

// Step 2: Verify token (when user clicks link)
const details = await getResetPasswordDetails(resetToken)

// Step 3: Reset password
await resetPassword(resetToken, token, newPassword, timezone)