API Key

An API key is a unique identifier passed with API requests to authenticate the calling application and control access to services.

An API key is a string token that a client includes in API requests to identify itself to the server. API keys serve as a simple authentication mechanism, allowing the API provider to track which application or developer is making requests, enforce usage quotas, and control access to specific endpoints or functionality.

How API keys work

When a developer registers with an API provider, they receive a unique API key. The client includes this key in each request, typically in one of three ways:

• HTTP header: Sent as a custom header such as X-API-Key: abc123 or via the standard Authorization header.

• Query parameter: Appended to the URL, e.g., ?api_key=abc123. This is simple but less secure because keys may appear in server logs, browser history, and referrer headers.

• Request body: Included as a field in the POST body. Less common and couples the key to the payload format.

The server validates the key against its records, identifies the caller, and decides whether to allow or deny the request based on the permissions associated with that key.

API keys vs. other authentication methods

API keys identify the calling application, but they have limitations compared to other approaches:

• API keys: Simple to implement and suitable for identifying applications and enforcing rate limits. However, they provide coarse-grained access control and are difficult to revoke selectively if leaked.

• JWT (JSON Web Tokens): Carry signed claims about the user's identity and permissions. They are self-contained, can expire, and support fine-grained authorization without a database lookup on every request.

• OAuth 2.0: A framework for delegated authorization, where a user grants an application limited access to their resources. More complex but appropriate for user-facing APIs where consent and scopes are important.

• Mutual TLS: Both client and server present certificates, providing strong identity verification at the transport layer. Primarily used in service-to-service communication.

In practice, many APIs combine API keys (for application identification and billing) with JWT or OAuth tokens (for user-level authentication and authorization).

Securing API keys

API keys should be treated as credentials:

• Store them in environment variables or secret managers, never in source code or version control.

• Transmit them only over HTTPS to prevent interception.

• Rotate keys periodically and revoke compromised keys immediately.

• Restrict each key's permissions to the minimum required scope.

• Use separate keys for development, staging, and production environments.

API keys and API gateways

An API gateway is a natural place to validate API keys because it processes every request before it reaches the backend. The gateway can check the key, enforce per-key rate limits, and reject unauthorized requests at the edge -- reducing load on backend services.

Serverless API Gateway supports JWT-based authorization through its authorizer configuration. For API key validation, teams can implement key checks in the backend services or use Cloudflare Workers custom logic alongside the gateway. The gateway's path configuration allows you to require authorization on specific endpoints while leaving others open, giving granular control over which routes need authentication.

Related documentation

• Authorizer Configuration - Configure JWT-based authentication at the gateway

• Path Routing - Apply authorization selectively per route

• Configuration Overview - General gateway configuration reference