Appearance

Server API Documentation ​

Overview ​

Server APIs are internal Nuxt server routes located in server/api/. These endpoints run on the Nuxt server and handle server-side operations like authentication, WebSocket authorization, and search proxying.

Key Characteristics ​

  • Internal Routes: Accessible via /api/* paths
  • Server-Side Only: Execute on the Nuxt server, not exposed to external clients
  • HTTP-Only Cookies: Secure token management using HTTP-only cookies
  • Proxy Pattern: Some endpoints act as secure proxies to external services

API Structure ​

server/api/
├── auth/            # Authentication endpoints
│   ├── set-session.post.ts
│   ├── clear-session.post.ts
│   ├── session.get.ts
│   ├── refresh-user.post.ts
│   ├── debug.get.ts          # Debug endpoint (dev only)
│   └── debug-post.post.ts    # Debug endpoint (dev only)
├── pusher/          # Pusher WebSocket auth
│   └── auth.post.ts
├── pdf/             # PDF proxy for asset preview
│   └── proxy.get.ts
├── txt/             # TXT proxy for asset preview
│   └── proxy.get.ts
└── typesense/       # Typesense search API
    ├── search.post.ts
    └── utils.ts              # Typesense utilities

API Categories ​

Authentication APIs ​

Server-side authentication endpoints that manage HTTP-only cookies:

Pusher APIs ​

WebSocket authorization proxy for Pusher channels:

Typesense APIs ​

Server-side Typesense search proxy:

Proxy APIs ​

Server-side proxies for asset preview (avoid CORS, add auth):

  • PDF Proxy - Proxies PDF asset URLs for in-app PDF viewer (GET /api/pdf/proxy?url=...)
  • TXT Proxy - Proxies plain-text asset URLs for in-app text viewer (GET /api/txt/proxy?url=...)

How Server APIs Work ​

Request Flow ​

  1. Client Request: Client makes request to /api/* endpoint
  2. Nuxt Server: Request is handled by Nuxt server route
  3. Server Processing: Server route executes server-side logic
  4. Response: Server returns response to client

Authentication Flow ​

Server APIs use HTTP-only cookies for authentication:

typescript
// Client-side (composable)
const { $api } = useNuxtApp()

// Request automatically includes HTTP-only cookie
await $api('/api/auth/session')
typescript
// Server-side (server/api/auth/session.get.ts)
export default defineEventHandler(async (event) => {
  // Read HTTP-only cookie (not accessible to client JavaScript)
  const token = getCookie(event, 'auth_token')
  
  // Process request...
  return { authenticated: !!token }
})

Security Features ​

  1. HTTP-Only Cookies: Tokens stored in HTTP-only cookies, not accessible to JavaScript
  2. Secure Flag: Cookies use secure flag in production (HTTPS only)
  3. SameSite Protection: SameSite=lax prevents CSRF attacks
  4. Server-Side Validation: All token validation happens on server
  5. No Token Exposure: Tokens never exposed to client JavaScript

Usage Examples ​

Authentication ​

typescript
// Set session after login
await $api('/api/auth/set-session', {
  method: 'POST',
  body: { token, userData }
})

// Get session status
const session = await $api('/api/auth/session')

// Clear session on logout
await $api('/api/auth/clear-session', {
  method: 'POST'
})
typescript
// Search via server proxy
const results = await $api('/api/typesense/search', {
  method: 'POST',
  body: {
    request: {
      q: 'logo',
      collections: ['assets']
    },
    commonSearchParams: {
      query_by: 'name,description',
      per_page: 20,
      page: 1
    },
    workspace_id_filter: workspaceId
  }
})

WebSocket Auth ​

typescript
// Laravel Echo automatically uses /api/pusher/auth
// No manual configuration needed

Environment Variables ​

Required environment variables for server APIs:

bash
# API Configuration
API_BASE_URL=https://api.example.com/
BACKEND_URL=https://backend.example.com

# Authentication
AUTH_SECRET=your-secret-key
SECURE_AUTH_COOKIE=true

# Typesense
TYPESENSE_HOST=search.example.com
TYPESENSE_PORT=443
TYPESENSE_PROTOCOL=https
TYPESENSE_API_KEY=your-api-key

# Pusher
PUSHER_KEY=your-pusher-key
PUSHER_CLUSTER=us2
PUSHER_AUTH_ENDPOINT=/api/pusher/auth

Best Practices ​

  1. Never Expose Tokens: Always use HTTP-only cookies for token storage
  2. Server-Side Validation: Validate all tokens on the server
  3. Error Handling: Handle errors gracefully and don't expose sensitive information
  4. Environment Checks: Use environment variables for configuration
  5. Security Headers: Set appropriate security headers in responses