Two API Keys, Zero Browser Exposure

Why One Key Isn't Enough

A Sitecore GraphQL API key carries three things that matter for security: an impersonation user (the identity the request runs as when no logged-in user is present), an AllowedControllers list, and a CORS Origin restriction. Item-level security is evaluated against whatever user is active for the request, so a key backed by a narrowly-scoped impersonation user is safe to expose — anonymous visitors only ever get back what that user is allowed to read.

The trouble starts when one key has to do double duty: rendering public pages and also driving full-text search across the content tree. Search indexes are often built from a broader slice of content than any single page exposes, so the impersonation user behind a search-capable key tends to have wider read access than the one behind a plain layout key. Expose that key to the browser — embed it in a client bundle or a query string — and anyone with DevTools open can copy it and query the search index directly, sidestepping whatever access rules the application layer was enforcing.

Splitting the Keys by Trust Level

The fix is to stop treating “the API key” as a single thing. Two keys, two impersonation users, two different exposure rules:

Architecture at a Glance

The browser only ever talks to the Next.js app's own origin. Public, role-trimmed GraphQL calls can go straight from the client using Key A. Search requests are routed through a dedicated API route that attaches Key B server-side before calling Sitecore — the browser never sees the search endpoint or the key that unlocks it.

The BFF Route

A Backend-for-Frontend route is just a server-side endpoint that sits between the browser and the real API so secrets and elevated-trust calls never cross that boundary. In this build, /api/search is that route: it accepts a search term from the client, builds the GraphQL query, attaches Key B from a server-only environment variable, and returns only the trimmed JSON the client needs.

// app/api/search/route.ts
import { NextRequest, NextResponse } from 'next/server';

const GRAPHQL_ENDPOINT = process.env.SITECORE_GRAPHQL_ENDPOINT!;
// server-only — note: no NEXT_PUBLIC_ prefix
const SEARCH_API_KEY = process.env.SITECORE_SEARCH_API_KEY!;

export async function GET(request: NextRequest) {
  const term = request.nextUrl.searchParams.get('q') ?? '';

  const query = `
    query Search($term: String!) {
      search(term: $term) {
        results { items { item { name url { path } } } }
      }
    }
  `;

  const scResponse = await fetch(GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      sc_apikey: SEARCH_API_KEY,
    },
    body: JSON.stringify({ query, variables: { term } }),
  });

  if (!scResponse.ok) {
    return NextResponse.json({ error: 'Search failed' }, { status: 502 });
  }

  return NextResponse.json(await scResponse.json());
}

On the client, the component only ever calls the app's own route:

// client component
const res = await fetch(`/api/search?q=${encodeURIComponent(term)}`);
const data = await res.json();

The browser's Network tab shows a request to /api/search on the app's own origin. It never sees SITECORE_GRAPHQL_ENDPOINT or SEARCH_API_KEY — those values exist only in the Node.js process running the route handler.

Wiring the Keys on the Sitecore Side

Each key is its own item under the GraphQL API Key location in the content tree, with three fields that do the actual enforcement:

• Impersonation User — the identity the request runs as when there's no logged-in visitor. Set this to a narrowly-scoped account for Key B, not an admin or a broadly-provisioned one.
• AllowedControllers — restricts which GraphQL controllers/operations the key can reach.
• CORS Origin — for Key A, lock this to the app's actual origins. Key B doesn't need a CORS entry at all, since it's never called from a browser context.

Field- and template-level filtering for the schema itself is configured separately, in Sitecore.Services.GraphQL.Content.config, which lets you exclude system fields (like __Layout) or entire template groups from what either key's schema can return — a second layer of trimming on top of item security.

Layering Authenticated Users on Top

Anonymous visitors aren't the whole story. Once Azure AD B2C federated login is in the mix, Sitecore GraphQL calls need to reflect the logged-in visitor's own role, not just Key A's anonymous impersonation user. Sitecore resolves this in one of two execution contexts: the impersonation-user context, which applies until a request carries no valid auth cookie, or the logged-in-user context, which applies once a valid Sitecore auth cookie is present. Whichever context is active, item security is evaluated against that user — which is why role-based restrictions defined once in the Security Editor apply automatically to GraphQL results.

At a high level, the federated login flow that puts a visitor into the right role looks like this:

Subsequent Layout Service and GraphQL calls from the app include that cookie, so Sitecore evaluates them as the authenticated virtual user and role — not the anonymous impersonation user behind Key A. The /api/search route keeps using Key B regardless of login state, since the search index's access model is managed independently from page-level content security.

Verifying Nothing Leaks

Before calling this pattern done, check it the way an attacker would:

Where This Breaks in Practice

Takeaways

Splitting one API key into two — one safe to expose because item security trims it, one kept strictly server-side because it isn't — is a small change with an outsized effect on the security model. Paired with a BFF route for the sensitive key and role-aware GraphQL calls for the authenticated path, it's the same trust-boundary pattern used everywhere else in a modern web app, applied consistently to Sitecore's GraphQL layer instead of carved out as a special case.

Frequently Asked Questions