SSG and Headless CMS: API Authentication Consistency Across Build Environments

Reliable method to keep API authentication consistent

The most reliable way to avoid build‑time authentication mismatches is to use a single code path that reads identically named environment variables in every context, and to validate those variables early in the build process.

Confirmed facts

• SSG data‑fetching functions (e.g., Next.js getStaticProps, Gatsby sourceNodes, Astro loaders, Eleventy data files) run in Node.js, where CORS is not enforced.
• Build failures that appear as 401/403 responses are almost always due to missing, malformed, or incorrectly scoped tokens, not CORS.
• Using different variable names or conditional logic based on "development" vs "production" creates a divergence between local .env* files and CI/CD‑injected secrets.

Steps to implement

1. Choose canonical variable names, for example:
• CMS_API_BASE_URL – the CMS endpoint.
• CMS_API_TOKEN – the token used for server‑side requests.
• CMS_PREVIEW (optional) – set to 1 to request draft/content preview.
2. In your SSG, read these variables exactly the same way in every environment:

// example for Next.js
const baseUrl = process.env.CMS_API_BASE_URL;
const token   = process.env.CMS_API_TOKEN;
const preview = process.env.CMS_PREVIEW === '1';

if (!baseUrl || !token) {
  throw new Error('Missing CMS API configuration – check CMS_API_BASE_URL and CMS_API_TOKEN');
}
// use baseUrl, token, preview in fetch calls

3. Provide values:
• Local development: a .env.local file (git‑ignored) containing the development token and preview flag.
• Production/CI: inject the same variable names as secrets or pipeline environment variables.
4. Add a CI step that prints the presence and length of each required variable (never the value) to catch missing injections early.
5. Keep the fetching logic free of environment branches; only the injected values differ.

Managing CORS in the Headless CMS

CORS only affects browser‑initiated requests (preview mode, client‑side fetches). Build‑time Node.js requests ignore CORS headers, so a build failure caused by CORS indicates a browser‑side issue, not a token problem.

Confirmed facts

• Bearer token Authorization headers are not cookies; they do not trigger the CORS credentials flag.
• A wildcard origin (*) cannot be used when credentials:true is required, and it is generally less secure than an explicit list.

Steps to configure CORS

1. Create an explicit origin allowlist that includes:
• Your production domain (e.g., https://www.example.com).
• Any staging or preview domains used by your CMS or Vercel/Netlify previews.
• Local development origins: http://localhost:3000 (or whatever port your SSG dev server uses).
2. Do not enable Access-Control-Allow-Credentials: true unless you are sending cookies or HTTP‑auth; for token‑based auth keep it omitted or set to false.
3. Verify the CMS response includes Access-Control-Allow-Origin matching the request origin exactly (including port).
4. Test from a browser on http://localhost using devtools to confirm the preflight succeeds.

Verification checklist

• Run the production build command locally with the production variable values (e.g., CMS_API_BASE_URL=… CMS_API_TOKEN=… next build) – a successful local run indicates parity with CI.
• Add a CI step that logs [[required]] CMS_API_BASE_URL: set (length = X) and the same for the token.
• Use curl to hit the CMS endpoint with the local token and, separately, with the CI token; compare status codes to isolate token versus network issues.
• From a browser on localhost, inspect the CMS response headers to confirm the origin is allowed.