May 25, 2026
Lock Down Your APIs: A Guide to API Key Authentication
API keys are lightweight, opaque tokens used to authenticate callers of an API. In WSO2 API Manager 4.7.0 and later, API keys are API-bound…
By Naduni Pamudika
3 min read
API keys are lightweight, opaque tokens used to authenticate callers of an API. In WSO2 API Manager 4.7.0 and later, API keys are API-bound — each key is scoped to a single API and cannot be reused across other APIs. This is a departure from the legacy application-bound model, making keys more targeted, auditable, and safer to distribute.
Unlike OAuth 2.0 flows, API keys are issued directly from the Developer Portal without any interaction with a Key Manager. This keeps the issuance path short and the tokens easy to manage for both internal and external consumers.
Key Characteristics
- API-specific scope — A key is linked to exactly one API. It cannot be used to invoke any other API on the gateway.
- Reduced attack surface — Compromise of one key cannot cascade to other APIs, limiting blast radius.
- Environment scoping — Keys are scoped to Production or Sandbox environments, keeping test traffic cleanly separated.
- Subscriptionless support — APIs that don't require subscriptions can use API keys without any application association.
- Simple gateway validation — The gateway checks the key-to-API mapping, IP/referrer restrictions, key expiry, and subscription status.
- No Key Manager round-trip — Keys are issued directly from the Developer Portal, making generation fast and lightweight.
Step-by-Step: Securing an API
Step 1 — Create and publish an API
- Sign in to the Publisher
Navigate to https://:9443/publisher and sign in.
- Deploy a sample API
Click Deploy Sample API to deploy the PizzaShack API (or create your own REST API).
- Enable API Key authentication
Go to Develop → API Configurations → Runtime, open Application Level Security, and check API Key.
- Save and deploy
Save the configuration, create a new revision if required, and deploy it to the gateway environment.
After enabling API Key authentication, remember to deploy a new revision of your API. Changes to security configuration only take effect after a fresh gateway deployment.
Step 2 — Generate the API Key
The generation flow differs slightly depending on whether subscriptions are required for your API.
In both cases you choose between Production and Sandbox environments. Copy the generated key and store it securely — it is displayed only once.
Invoking the Secured API
Pass the API key as a request header. The default header name is apikey:
curl -k -H "apikey: <YOUR_API_KEY>" \
"https://localhost:8243/pizzashack/1.0.0/menu"curl -k -H "apikey: <YOUR_API_KEY>" \
"https://localhost:8243/pizzashack/1.0.0/menu"Regenerating and Revoking Keys
Regenerating a key
Navigate to the same API Keys tab where the key was generated. Click Regenerate to invalidate the old key and issue a new one immediately. The old key stops working the moment regeneration completes.
Revoking a key
Keys can be revoked from two places depending on who initiates the action:
IP Address & HTTP Referrer Restrictions
API keys alone offer no protection if a key leaks to an unauthorized caller. WSO2 API Manager supports two additional restriction mechanisms that bind the key to a specific origin:
IP address restriction
Specify one or more allowed IP addresses or CIDR ranges when generating or managing the key. Requests arriving from any other IP are rejected at the gateway with a 401 Unauthorized response, even if the key itself is valid.
# Only the listed IPs may use this key
Allowed IPs: 203.0.113.42, 10.0.0.0/24# Only the listed IPs may use this key
Allowed IPs: 203.0.113.42, 10.0.0.0/24HTTP referrer restriction
For browser-facing APIs, configure allowed referrer header values. The gateway checks the incoming referrer header against the allowlist and rejects requests whose origin does not match. This is particularly useful for protecting public APIs embedded in web frontends.
# Only requests from these referrers are allowed
Allowed Referrers: https://myapp.example.com/*, https://staging.example.com/*# Only requests from these referrers are allowed
Allowed Referrers: https://myapp.example.com/*, https://staging.example.com/*The referrer header is browser-controlled and can be spoofed by non-browser clients. Use IP restrictions as the stronger control; referrer restrictions are a defense-in-depth layer, not a primary security boundary.
Best Practices
- Treat API keys like passwords
Never embed keys directly in source code. Use environment variables, secrets managers (e.g. HashiCorp Vault), or CI/CD secret stores to inject keys at runtime.
- Prefer header-based transmission
Always pass the key via the apikey header rather than as a query parameter to avoid accidental logging or leakage.
- Apply IP and referrer restrictions
Bind keys to known IP ranges or trusted referrer origins wherever your architecture permits, adding a second layer of defence beyond the token itself.
- Rotate keys regularly
Establish a rotation policy (e.g. every 90 days) and automate it where possible. Use the regenerate function to minimise downtime during rotation.
- Use separate keys per environment
Always generate distinct Production and Sandbox keys. This prevents test traffic from reaching production backends and makes audit trails cleaner.
- Monitor and alert on anomalies
Enable API analytics to track usage patterns per key. Sudden spikes or calls from unexpected geographies are signals of a compromised key — revoke immediately.
API keys in WSO2 API Manager 4.7.0 provide a lightweight, API-scoped authentication mechanism that is quick to issue, easy to revoke, and straightforward to restrict by IP or referrer. Combined with environment scoping, rate limiting, and regular rotation, they form a solid first line of defence for your APIs.