Authentication & Security (Clerk)

Relevant source files

The following files were used as context for generating this wiki page:

• server/security/auth.ts
• frontend/src/root.tsx
• server/index.ts
• frontend/src/features/auth/containers/SignInPageContainer.tsx
• frontend/src/features/auth/containers/SignUpPageContainer.tsx
• server/shared/convexClient.ts

The authentication and security system in the Bot-Auto-IG project is built primarily using Clerk for user identity management and session handling. It provides a multi-layered security approach including frontend route protection, backend middleware validation, and a secondary internal API key mechanism for server-to-server communication, specifically for automated tasks like Convex cron jobs.

Sources: server/security/auth.ts:1-12, frontend/src/root.tsx:1-12

System Architecture

The security architecture spans the entire stack, utilizing Clerk's React Router integration on the frontend and Express middleware on the backend. The backend is configured to handle both standard user sessions and internal requests that bypass Clerk authentication via a secure bearer token.

Security Components Overview

Component	Responsibility	Source
ClerkProvider	Root context for auth state in the React application.	frontend/src/root.tsx:103-107
clerkMiddleware	Backend middleware that parses and validates Clerk session tokens.	server/index.ts:74, server/security/auth.ts:7
requireApiAuth	Enforces that a valid user session exists for a specific API route.	server/security/auth.ts:10
Internal API Key	Provides access for server-to-server calls (e.g., Convex cron jobs).	server/security/auth.ts:25-41
automationLimiter	Rate limits sensitive automation-related endpoints.	server/index.ts:82

Frontend Authentication Flow

The frontend utilizes @clerk/react-router to manage user sessions. The root layout is wrapped in a ClerkProvider which uses a publishable key from environment variables.

Sign-In and Sign-Up Logic

The application implements custom sign-in and sign-up containers that interact with the Clerk SDK to handle credentials and email verification codes.

Backend Security & Middleware

The Express server implements security through a combination of Clerk authentication, internal API keys, and CORS policies.

Hybrid Authentication Middleware

The server defines a specialized middleware requireApiAuthOrInternalKey. This allows flexibility for endpoints like /api/workflows which may be called by a logged-in user or an automated internal process.

Route Protection Configuration

Routes are protected based on their sensitivity and intended caller:

Route Pattern	Security Requirement	Middleware Used
/api/health	Public	None
/api/automation	Valid Clerk User	requireApiAuth
/api/workflows	User OR Internal Key	requireApiAuthOrInternalKey
/api/monitoring	Valid Clerk User + Rate Limit	requireApiAuth, apiLimiter

Sources: server/index.ts:77-88

Internal API Key Management

For communication between the server and external database services (Convex), the system uses an INTERNAL_API_KEY. This key is loaded from the environment and verified in the Authorization header as a Bearer token.

// server/security/auth.ts:31-41
export function requireApiAuthOrInternalKey(req: Request, res: Response, next: NextFunction) {
    const authHeader = req.headers.authorization || ''

    // Check for internal API key first
    if (INTERNAL_API_KEY && authHeader === `Bearer ${INTERNAL_API_KEY}`) {
        logger.debug('Internal API key matched')
        return next()
    }

    // Fall back to Clerk auth
    return requireAuth()(req, res, next)
}

Sources: server/security/auth.ts:31-41

Environment Security

Sensitive configuration is managed via environment variables and never committed to the repository. Key security-related environment variables include:

• INTERNAL_API_KEY: Used for server-to-server and Convex HTTP auth.
• CLERK_PUBLISHABLE_KEY: Used by the frontend React application.
• CONVEX_URL: Targeted database endpoint for authenticated requests.
• ALLOWED_ORIGINS: Used to configure CORS for production environments.

Sources: server/shared/convexClient.ts:16-24, server/index.ts:40, frontend/src/root.tsx:105

Summary

The "Authentication & Security (Clerk)" system ensures that all user actions are verified through Clerk's identity platform while maintaining high availability for internal automation through a secure API key bypass. This dual-path authentication strategy allows the project to scale from simple user-triggered workflows to complex, cron-scheduled automation tasks without compromising security.