Web API Routes (Next.js)

All routes live under apps/web/src/app/api/. These handle server-side operations that require access to Firebase Admin SDK or Stripe secrets — operations that cannot be performed from the browser.

---

Authentication & Sessions

Route	Method	Auth	Description
/api/auth/session	POST	Bearer ID token	Creates HTTP-only __session cookie via Firebase Admin createSessionCookie()
/api/auth/session	DELETE	—	Clears the __session cookie

The __session cookie is the primary auth mechanism for the web app. It's set as HTTP-only to prevent XSS access and is verified server-side on protected routes.

---

Billing & Subscriptions

Route	Method	Auth	Description
/api/create-checkout-session	POST	Bearer ID token	Creates a Stripe Checkout session. Body: { planId: "starter" | "pro" }. Returns { sessionId }
/api/verify-session	POST	—	Finalizes subscription after checkout. Body: { sessionId }. Returns { subscription, customToken, success }
/api/billing/portal	POST	__session cookie	Creates a Stripe Billing Portal session. Returns { url }
/api/billing/change-plan	POST	Bearer ID token	Instant plan upgrade. Body: { planId }. Returns { success, subscription, requiresAction?, paymentIntentClientSecret? }

Checkout flow notes

• create-checkout-session validates the stored Stripe customer, reuses by email if the stored ID is missing, or creates a new customer
• verify-session uses the session_id to look up the Stripe session, find/create the user, link stripeCustomerId, and upsert the subscription document
• When change-plan returns requiresAction: true, confirm the paymentIntentClientSecret via Stripe.js before refreshing claims

---

Credits

Route	Method	Auth	Description
/api/credits/balance	GET	__session cookie	Returns { balance, periodStart, periodEnd, planId, priceId }

---

API Keys & Request Logs

Route	Method	Auth	Description
/api/api-keys	GET	__session cookie	List all API keys for the authenticated user
/api/api-keys	POST	__session cookie	Create a new API key. Mirrors hashed key to root apiKeys/{hash} for Functions validation
/api/api-keys/[id]	DELETE	__session cookie	Revoke a key by ID. Mirrors revocation to root apiKeys/{hash}
/api/api-requests	GET	__session cookie	Paginated list of recent Public API requests from users/{uid}/apiRequests

---

Library

Route	Method	Auth	Description
/api/library/upload-url	POST	__session cookie	Generates a signed upload URL for library assets
/api/library/folders/[folderId]	GET/POST	__session cookie	List or manage library folder contents

---

Webhooks

Route	Method	Auth	Description
/api/webhooks/firstpromoter	POST	Signature	FirstPromoter referral tracking webhook

Stripe webhooks are handled by the Firebase Function stripeWebhook, not by a Next.js API route. Configure the Stripe Dashboard to point to your deployed Cloud Functions URL.

---

Utilities

Route	Method	Auth	Description
/api/debug-env	GET	—	Shows which environment variables are present (not their values)
/api/tiktok/callback	GET	—	Local desktop OAuth proxy for TikTok development

---

Middleware

The Next.js middleware (src/middleware.js) enforces the presence of __session cookie on protected paths:

• /dashboard/*
• /create/*
• /posts/*
• /settings/*
• /admin/*
• /automations/*
• /billing/*
• /library/*
• /templates/*

Requests without a valid session cookie are redirected to the sign-in page.

---

Frontend Usage

• AuthContext triggers POST /api/auth/session whenever the Firebase ID token changes (sign-in, refresh)
• Checkout success page calls POST /api/verify-session to finalize the subscription
• Settings page manages API keys via the /api/api-keys routes
• Billing page opens the Stripe portal via POST /api/billing/portal

---

Related docs

• Authentication — Full auth flow documentation
• Subscriptions — Stripe integration details
• Public API v1 — External API (served by Cloud Functions)
• Functions API — OAuth and publish endpoints