Next.js API Keys: Scoped Access, Rotation & Revocation

Give each integration an accountable identity

API keys let external systems call a Next.js application without an interactive login. A key is a bearer credential: whoever obtains it can exercise its assigned authority. Design the identity and permissions first, then decide how the credential is issued, verified, rotated, and revoked.

Separate test and production credentials, and issue a distinct key for each integration. Shared credentials make attribution, targeted revocation, and migration difficult. For delegated user access or sensitive workflows, evaluate stronger authentication appropriate to the client and use case.

Generate unpredictable secrets and reveal them once

Use a cryptographically secure random generator for the secret. A useful token format combines an environment marker, a public lookup identifier, and a high-entropy secret. The marker and identifier help operators locate the record; they do not provide security and must never replace verification.

Require an authorized administrator to create a key, show the granted scopes and expiry before confirmation, and return the secret only at creation. Set the response to avoid caching and keep the secret out of analytics, error reports, and rendered page data. Show the public identifier and masked suffix on later visits.

Record creator, tenant, principal, label, scopes, issued time, expiry, and status. An owner should remain accountable even when the original creator leaves the organization.

Store a verifier instead of a retrievable credential

For application-issued random bearer secrets, store a cryptographic verifier rather than the plaintext secret. A keyed digest can add protection against a database-only disclosure when its verifier key is held separately. Document the algorithm and verifier-key version so that key maintenance remains possible.

Bound token length and parse its format before lookup. Retrieve by the public identifier, compute the verifier using the correct version, and compare fixed-length values with a constant-time comparison. Check expiry, revocation, environment, tenant status, and principal status before creating the trusted request context.

Enforce scopes and resource ownership on every request

Use a small permission vocabulary such as orders:read or imports:create, backed by an explicit route-to-permission map. Deny unspecified capabilities by default. Scope grants should be bounded by the issuing actor's authority and the integration principal's policy.

// Illustrative request boundary
const principal = await authenticateApiKey(request);
requireScope(principal, "orders:read");
const order = await orders.findForTenant({
  tenantId: principal.tenantId,
  orderId: requestedOrderId,
});
return permittedOrderFields(order);

A scope allows an operation; tenant and resource checks decide which records it can affect. Ignore client-supplied tenant identity unless a specific cross-tenant capability authorizes it. Recheck commercial entitlements and suspended-account rules independently of the key's original grant.

Keep secrets in protected server-to-server requests

Require HTTPS and send the key in the documented request header. Avoid query strings, redirects, and URLs because credentials can enter logs and copied links. The OWASP REST Security Cheat Sheet covers this leakage boundary and cautions against relying solely on API keys for high-value resources.

Do not place privileged keys in browser bundles or mobile clients that distribute the secret to users. Keep outbound provider credentials behind server code using the boundaries in our Next.js secrets guide. Redact credential headers in application logs, reverse proxies, tracing agents, and support tooling.

Rotate with a bounded overlap and observable handover

Create a replacement credential with the intended permissions, deliver it through an approved secret channel, and let the integration deploy it. Track successful use of the new public key identifier. Retire the old credential after a short, explicit overlap window and verify that no required workload still depends on it.

Keep both credentials tied to the same principal while maintaining separate usage evidence. Prevent the rotation operation from expanding privileges accidentally. For an exposed key, revoke immediately and repair the integration afterward; an overlap period would preserve the compromised authority.

Make revocation latency an explicit operating target

A revoked database record is ineffective if application nodes cache its active status for an hour. Choose a short verification-cache lifetime, distribute invalidations where needed, and define the maximum time until rejection across regions and instances. High-risk operations may need a fresh status check.

Revoke keys when an integration is removed, a tenant closes, ownership changes under policy, or exposure is suspected. In-flight work and queued jobs need a defined rule: revoke future requests and re-authorize deferred work before it performs sensitive effects. Record the action and actor using our audit logging guide.

Apply quotas to both credentials and principals

Limit requests by key and also by tenant or principal so issuing more keys cannot bypass an aggregate budget. Bound payload size, expensive queries, batch work, and concurrency. Apply strict controls to malformed or unknown-key traffic before expensive verification.

Record safe key identifiers, route, response class, granted operation, latency, and approximate last-use time. Aggregate last-use updates to avoid a database write per request. Detect unfamiliar activity patterns, sudden volume changes, and repeated denied operations without storing the credential itself. Our rate-limiting guide explains distributed limits and caller identification.

Test the credential lifecycle and denial paths

Verify that invalid, expired, revoked, wrong-environment, and disabled-principal keys fail consistently. Test a valid key against the wrong tenant, missing scope, forbidden field, suspended account, and exhausted quota. Confirm that responses never reveal whether a guessed identifier belongs to another customer.

Exercise rotation while requests are active, revocation with warm caches, verifier-key version changes, and authorization of delayed jobs. Search representative logs and traces for test secrets to prove redaction at every layer. Keep emergency revocation procedures available to the operators who respond to credential incidents.

Next.js API key checklist