Appearance

Pusher Authentication API ​

Overview ​

The auth.post.ts endpoint provides a secure WebSocket authorization proxy for Pusher channels. It reads the auth token from the HTTP-only cookie and forwards the authorization request to the backend Pusher auth endpoint.

Endpoint ​

Path: POST /api/pusher/auth

File: server/api/pusher/auth.post.ts

Request Body ​

typescript
{
  socket_id: string      // Pusher socket ID (required)
  channel_name: string   // Channel name to authorize (required)
}

Response ​

typescript
{
  auth: string           // Authorization signature
  channel_data?: string  // Channel data (for presence channels)
}

Features ​

Secure Proxy Pattern ​

  • Reads auth_token from HTTP-only cookie
  • Forwards authorization request to backend
  • Token never exposed to client JavaScript
  • Acts as secure proxy between client and backend

Backend Integration ​

The endpoint constructs the backend Pusher auth URL:

typescript
const authUrl = pusherAuthEndpoint.startsWith('http') 
  ? pusherAuthEndpoint 
  : `${apiBaseUrl}${pusherAuthEndpoint.replace(/^\//, '')}`

Authorization Header ​

Forwards token in Authorization header:

typescript
headers: {
  'Authorization': `Bearer ${token}`
}

Error Handling ​

Missing Token ​

typescript
throw createError({
  statusCode: 401,
  statusMessage: 'Authentication required'
})

Missing Parameters ​

typescript
throw createError({
  statusCode: 400,
  statusMessage: 'socket_id and channel_name are required'
})

Configuration Error ​

typescript
throw createError({
  statusCode: 500,
  statusMessage: 'Pusher auth endpoint not configured'
})

Backend Errors ​

typescript
throw createError({
  statusCode: error.statusCode || error.status || 500,
  statusMessage: error.statusMessage || error.message || 'Pusher authorization failed'
})

Usage ​

Automatic Usage (Laravel Echo) ​

Laravel Echo automatically uses this endpoint. No manual configuration needed:

typescript
// In app/plugins/laravel-echo.client.ts
const echo = new Echo({
  broadcaster: 'pusher',
  key: config.public.pusherKey,
  cluster: config.public.pusherCluster,
  authEndpoint: '/api/pusher/auth',  // Automatically used
  // ...
})

Manual Usage ​

typescript
const { $api } = useNuxtApp()

// Authorize private channel
const response = await $api('/api/pusher/auth', {
  method: 'POST',
  body: {
    socket_id: pusherSocketId,
    channel_name: 'private-channel-name'
  }
})

// Use auth signature
const authSignature = response.auth

Configuration ​

Environment Variables ​

bash
PUSHER_KEY=your-pusher-key
PUSHER_CLUSTER=us2
PUSHER_AUTH_ENDPOINT=/api/pusher/auth
API_BASE_URL=https://api.example.com/

Runtime Config ​

typescript
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      pusherAuthEndpoint: process.env.PUSHER_AUTH_ENDPOINT,
      apiBaseUrl: process.env.API_BASE_URL
    }
  }
})

Security Considerations ​

  1. HTTP-Only Cookie: Token read from HTTP-only cookie
  2. Server-Side Proxy: Authorization happens on server
  3. No Token Exposure: Token never exposed to client
  4. XSS Protection: Prevents XSS token theft
  5. Backend Validation: Backend validates user permissions for channels

Channel Types ​

Private Channels ​

typescript
// Channel name: private-user-123
// Backend validates user has access to user-123

Presence Channels ​

typescript
// Channel name: presence-room-456
// Backend returns channel_data with user info