Authentication

Overview

SubPirate Pro uses JWT (JSON Web Token) authentication powered by Supabase Auth. All API endpoints (except /health and /api/test) require a valid JWT token in the Authorization header.

Getting a JWT Token

Tokens are obtained through Supabase Auth authentication flows: Users authenticate via the frontend application, which uses Supabase Auth with PKCE flow:

Email/Password: Traditional email and password authentication
OAuth Providers: Google OAuth (additional providers can be configured)

The frontend manages the authentication flow automatically. Once authenticated, the JWT access token is available from the Supabase session.

2. Frontend Token Retrieval

In the frontend application, tokens are automatically retrieved and attached to requests using the secureFetch() utility:

import { secureFetch } from '@/lib/fetch';

// Automatically includes JWT token
const response = await secureFetch('/api/subscription');
const data = await response.json();

The secureFetch() function (from src/lib/fetch.ts) automatically:

Retrieves the current Supabase session
Extracts the access_token
Adds it to the Authorization header

Authorization Header Format

Include the JWT token in the Authorization header using the Bearer scheme:

Authorization: Bearer <your-jwt-token>

Example Request

curl -X GET \
  http://localhost:8787/api/subscription \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Token Validation

The API validates tokens using Supabase Auth’s getUser() method:

Extract Token: The server extracts the Bearer token from the Authorization header
Validate with Supabase: Token is validated against Supabase Auth
Verify User: User information is extracted from the validated token
Attach to Request: User data is attached to req.user for downstream handlers

Server-Side Implementation

From server.js:server.js:208-243:

async function requireAuth(req, res, next) {
  const token = getBearerToken(req);
  
  if (!token) {
    return res.status(401).json({ 
      error: 'Missing Authorization bearer token' 
    });
  }

  const { data, error } = await supabaseAuth.auth.getUser(token);
  
  if (error || !data?.user) {
    return res.status(401).json({ 
      error: 'Invalid or expired token' 
    });
  }

  req.user = data.user;
  req.accessToken = token;
  next();
}

Token Lifecycle

Expiration

string

JWT tokens expire after a configurable period (default: 1 hour). The frontend automatically handles token refresh using Supabase’s session management.

Refresh

string

When a token expires, Supabase automatically attempts to refresh it using the refresh token stored in the session. This happens transparently in the frontend.

Revocation

string

Tokens are immediately invalidated when a user signs out. The Supabase session is cleared, and subsequent API requests with the old token will fail with 401 Unauthorized.

Local Admin Bypass (Development Only)

For local development and testing, SubPirate Pro includes an admin bypass mechanism that allows API access without a Supabase session.

This feature is only available in development mode and is automatically disabled in production.

Enabling Local Admin Mode

Set these environment variables:

LOCAL_ADMIN_BYPASS=1
LOCAL_ADMIN_TOKEN=your-secret-dev-token

Or using VITE_ prefixes for frontend access:

VITE_LOCAL_ADMIN_BYPASS=1
VITE_LOCAL_ADMIN_TOKEN=your-secret-dev-token

How It Works

Frontend: When enabled, secureFetch() uses the local admin token instead of retrieving a Supabase session:

// From src/lib/fetch.ts:5-12
if (isLocalAdminSessionActive()) {
  headers.set('Authorization', 
    `Bearer ${import.meta.env.VITE_LOCAL_ADMIN_TOKEN}`);
  return fetch(url, { ...options, headers });
}

Backend: The server recognizes the local admin token and creates a synthetic admin user:

// From server.js:212-223
if (localAdminEnabled && token === localAdminToken) {
  req.user = { 
    id: '00000000-0000-4000-8000-000000000000', 
    email: 'local-admin@localhost' 
  };
  req.isLocalAdmin = true;
  return next();
}

Database Access: Local admin requests use the Supabase service role client, which bypasses Row Level Security (RLS) policies:

// From server.js:246-248
function getAuthedSupabaseClient(req) {
  if (req?.isLocalAdmin) {
    return supabaseService; // Service role = bypass RLS
  }
  // ... regular user client
}

Security Safeguards

Production Block

string

The server explicitly ignores LOCAL_ADMIN_BYPASS=1 in production:

// server.js:176-178
if (isProduction && localAdminBypassFlag === '1') {
  console.warn('LOCAL_ADMIN_BYPASS is ignored in production for security.');
}

Origin Validation

string

Even with local admin enabled, requests must come from allowed CORS origins (defaults to localhost/127.0.0.1 in dev).

Example Usage

# Set in .env
LOCAL_ADMIN_BYPASS=1
LOCAL_ADMIN_TOKEN=dev-secret-123

# Make request with local admin token
curl -X GET \
  http://localhost:8787/api/subscription \
  -H "Authorization: Bearer dev-secret-123" \
  -H "Content-Type: application/json"

Authentication Errors

Missing Token

{
  "error": "Missing Authorization bearer token"
}

Status Code: 401 Unauthorized Cause: No Authorization header present in the request Solution: Include the Bearer token in the header

Invalid or Expired Token

{
  "error": "Invalid or expired token"
}

Status Code: 401 Unauthorized Cause: Token is malformed, expired, or revoked Solution: Obtain a fresh token by re-authenticating

Configuration Error

{
  "error": "Supabase server auth is not configured. Set SUPABASE_URL and SUPABASE_ANON_KEY (or VITE_SUPABASE_URL/VITE_SUPABASE_ANON_KEY)."
}

Status Code: 500 Internal Server Error Cause: Server environment variables are not configured Solution: Ensure SUPABASE_URL and SUPABASE_ANON_KEY are set on the server

User Context

Once authenticated, user information is available in the request context:

req.user.id

string

Unique user ID (UUID format)

req.user.email

string

User’s email address

req.accessToken

string

The JWT access token used for the request

req.isLocalAdmin

boolean

true if using local admin bypass (development only)

Best Practices

Token Storage: Never store JWT tokens in localStorage. The frontend uses Supabase’s built-in session management, which handles secure token storage automatically.

Token Refresh: Let Supabase handle token refresh automatically. The secureFetch() utility always retrieves the current session, ensuring you’re using fresh tokens.

Error Handling: Always handle 401 responses by redirecting users to the login page. This indicates their session has expired.

Never commit tokens: Ensure .env files are in .gitignore. Never commit actual JWT tokens or the LOCAL_ADMIN_TOKEN to version control.

Getting Started

Reddit API

Analysis

Campaigns

Admin

Overview

Getting a JWT Token

2. Frontend Token Retrieval

Authorization Header Format

Example Request

Token Validation

Server-Side Implementation

Token Lifecycle

Local Admin Bypass (Development Only)

Enabling Local Admin Mode

How It Works

Security Safeguards

Example Usage

Authentication Errors

Missing Token

Invalid or Expired Token

Configuration Error

User Context

Best Practices

Build docs developers (and LLMs) love

Getting Started

Reddit API

Analysis

Campaigns

Admin

Documentation Index

​Overview

​Getting a JWT Token

​1. Sign In

​2. Frontend Token Retrieval

​Authorization Header Format

​Example Request

​Token Validation

​Server-Side Implementation

​Token Lifecycle

​Local Admin Bypass (Development Only)

​Enabling Local Admin Mode

​How It Works

​Security Safeguards

​Example Usage

​Authentication Errors

​Missing Token

​Invalid or Expired Token

​Configuration Error

​User Context

​Best Practices

Build docs developers (and LLMs) love

Overview

Getting a JWT Token

1. Sign In

2. Frontend Token Retrieval

Authorization Header Format

Example Request

Token Validation

Server-Side Implementation

Token Lifecycle

Local Admin Bypass (Development Only)

Enabling Local Admin Mode

How It Works

Security Safeguards

Example Usage

Authentication Errors

Missing Token

Invalid or Expired Token

Configuration Error

User Context

Best Practices