cannaiq/backend/docs/API_SECURITY.md

API Security Documentation

This document describes the authentication and authorization configuration for all CannaiQ API endpoints.

Authentication Methods

1. Trusted Origins (No Token Required)

Requests from trusted sources are automatically authenticated with internal role:

Trusted IPs:

• 127.0.0.1 (localhost IPv4)
• ::1 (localhost IPv6)
• ::ffff:127.0.0.1 (IPv4-mapped IPv6)

Trusted Domains:

• https://cannaiq.co
• https://www.cannaiq.co
• https://findadispo.com
• https://www.findadispo.com
• https://findagram.co
• https://www.findagram.co
• http://localhost:3010
• http://localhost:8080
• http://localhost:5173

Trusted Patterns:

• *.cannabrands.app
• *.cannaiq.co

Internal Header:

• X-Internal-Request header matching INTERNAL_REQUEST_SECRET env var

2. Bearer Token Authentication

External requests must include a valid token:

Authorization: Bearer <token>

Token Types:

• JWT Token: User session tokens (7-day expiry)
• API Token: Long-lived tokens for integrations (stored in api_tokens table)

Authorization Levels

Public (No Auth)

Routes accessible without authentication:

• GET /health - Health check
• GET /api/health/* - Comprehensive health endpoints
• GET /outbound-ip - Server's outbound IP
• GET /api/v1/deals - Public deals endpoint

Authenticated (Trusted Origin or Token)

Routes requiring authentication but no specific role:

Route	Description
/api/payloads/*	Raw crawl payload access
/api/workers/*	Worker monitoring
/api/worker-registry/*	Worker registration and heartbeats
/api/stores/*	Store CRUD
/api/products/*	Product listing
/api/dispensaries/*	Dispensary data

Admin Only (Requires admin or superadmin role)

Routes restricted to administrators:

Route	Description
/api/job-queue/*	Job queue management
/api/k8s/*	Kubernetes control (scaling)
/api/pipeline/*	Pipeline stage transitions
/api/tasks/*	Task queue management
/api/admin/orchestrator/*	Orchestrator dashboard
/api/admin/trusted-origins/*	Manage trusted origins
/api/admin/debug/*	Debug endpoints

Note: The internal role (localhost/trusted origins) bypasses role checks, granting automatic admin access for local development and internal services.

Endpoint Security Matrix

Endpoint Group	Auth Required	Role Required	Notes
/api/payloads/*	Yes	None	Query API for raw crawl data
/api/job-queue/*	Yes	admin	Legacy job queue (deprecated)
/api/workers/*	Yes	None	Worker status monitoring
/api/worker-registry/*	Yes	None	Workers register via trusted IPs
/api/k8s/*	Yes	admin	K8s scaling controls
/api/pipeline/*	Yes	admin	Store pipeline transitions
/api/tasks/*	Yes	admin	Task queue CRUD
/api/admin/orchestrator/*	Yes	admin	Orchestrator metrics/alerts
/api/admin/trusted-origins/*	Yes	admin	Auth bypass management
/api/v1/*	Varies	Varies	Public API (per-endpoint)
/api/consumer/*	Varies	Varies	Consumer features

Implementation Details

Middleware Stack

// Authentication middleware - validates token or trusted origin
import { authMiddleware } from '../auth/middleware';

// Role requirement middleware - checks user role
import { requireRole } from '../auth/middleware';

// Usage in route files:
router.use(authMiddleware);                           // All routes need auth
router.use(requireRole('admin', 'superadmin'));       // Admin-only routes

Auth Middleware Flow

Request → Check Bearer Token
         ├─ Valid JWT → Set user from token → Continue
         ├─ Valid API Token → Set user as api_token role → Continue
         └─ No Token → Check Trusted Origin
                      ├─ Trusted → Set user as internal role → Continue
                      └─ Not Trusted → 401 Unauthorized

Role Check Flow

Request → authMiddleware → requireRole('admin')
                          ├─ role === 'internal' → Continue (bypass)
                          ├─ role in ['admin', 'superadmin'] → Continue
                          └─ else → 403 Forbidden

Worker Pod Authentication

Worker pods (in Kubernetes) authenticate via:

1. Internal IP: Pods communicate via cluster IPs, which are trusted
2. Internal Header: Optional X-Internal-Request header for explicit trust

Endpoints used by workers:

• POST /api/worker-registry/register - Report for duty
• POST /api/worker-registry/heartbeat - Stay alive
• POST /api/worker-registry/deregister - Graceful shutdown
• POST /api/worker-registry/task-completed - Report task completion

API Token Management

API tokens are managed via:

• GET /api/api-tokens - List tokens
• POST /api/api-tokens - Create token
• DELETE /api/api-tokens/:id - Revoke token

Token properties:

• token: The bearer token value
• name: Human-readable identifier
• rate_limit: Requests per minute
• expires_at: Optional expiration
• active: Enable/disable toggle
• allowed_endpoints: Optional endpoint restrictions

Security Best Practices

1. Never expose tokens in URLs - Use Authorization header
2. Use HTTPS in production - All traffic encrypted
3. Rotate API tokens periodically - Set expiration dates
4. Monitor rate limits - Prevent abuse
5. Audit access logs - Track API usage via api_usage_logs table

Related Files

• src/auth/middleware.ts - Auth middleware implementation
• src/routes/api-tokens.ts - Token management endpoints
• src/middleware/apiTokenTracker.ts - Usage tracking
• src/middleware/trustedDomains.ts - Domain trust markers