Lab 2 — API Key Security¶
Goal: gate the /orders flow behind VerifyAPIKey, create a real
API product / developer / app, and watch anonymous requests get rejected.
~20 min.
What you'll learn¶
- The product → developer → app → credential chain
- How
VerifyAPIKeyenriches the request with app metadata - Why you should strip the key before it reaches the backend
Before you start
You need a deployed labs-proxy (Lab 1). Be ready to
state, from memory, what proxy.pathsuffix is.
The chain¶
An API key is only meaningful because a product defines what it unlocks (which proxies/paths) and an app binds a credential to a developer.
Provision the chain¶
export TOKEN=$(gcloud auth print-access-token)
# 1. Product — scopes access to the labs-proxy
apigeecli products create -o "$APIGEE_ORG" -t "$TOKEN" \
-n labs-product \ # (1)!
--displayname "Labs Product" \
--envs "$APIGEE_ENV" \ # (2)!
--proxies labs-proxy \ # (3)!
--approval auto \ # (4)!
--quota 10000 --interval 1 --unit month # (5)!
# 2. Developer
apigeecli developers create -o "$APIGEE_ORG" -t "$TOKEN" \
-n labs -f Lab -l User --user labsuser --email you@example.com # (6)!
# 3. App bound to the product → prints consumerKey + consumerSecret
apigeecli apps create -o "$APIGEE_ORG" -t "$TOKEN" \
-n labs-app --email you@example.com \ # (7)!
--prods labs-product # (8)!
- Machine name of the product; this is what apps reference.
- Product is valid only in these environments. A key for a product that isn't enabled in the env you call is rejected.
- Which deployed proxies the product unlocks. Omit it and nothing is covered. (You can also restrict by path with operation groups.)
auto= keys are approved immediately;manual= an admin must approve each one.- Informational/billing-oriented quota on the product — 10,000 calls a
month. The
Quotapolicy in the proxy is what enforces limits at runtime (Lab 4). - Developers are people/teams; the email is their identity. It surfaces as
developer.emailin the flow. - Which developer owns the app. App and developer are separate objects so one developer can have many apps.
- Attach the app to the product — this link is what makes its key work for
labs-proxy. Output includesconsumerKey(the API key) andconsumerSecret(used in Lab 3).
Save the key:
The policy¶
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="VA-CheckAPIKey"> <!-- (1)! -->
<DisplayName>VA-CheckAPIKey</DisplayName>
<APIKey ref="request.queryparam.apikey"/> <!-- (2)! -->
</VerifyAPIKey>
continueOnError="false"is the security-critical bit: if the check fails the flow must abort. Setting this totrueon an auth policy turns it into a decoration, not a gate.- Where to find the key: the variable reference (
ref) is read at runtime.request.queryparam.apikey=?apikey=.... Swap inrequest.header.x-apikeyto read a header. A missing value faults withFailedToResolveAPIKey; a present-but-unknown one withInvalidApiKey.
It sits in the get-orders conditional flow — /hello stays open, /orders
is protected:
<Flow name="get-orders">
<Condition>(proxy.pathsuffix MatchesPath "/orders") and (request.verb = "GET")</Condition>
<Request>
<Step><Name>VA-CheckAPIKey</Name></Step> <!-- (1)! -->
<Step><Name>Quota-PerApp</Name></Step> <!-- (2)! -->
<Step><Name>AM-StripKey</Name></Step> <!-- (3)! -->
</Request>
...
</Flow>
- Gate: unauthenticated callers stop here.
- Needs
verifyapikey.VA-CheckAPIKey.client_id, produced by the line above. - Cleanup after we've read what we need from the query string, before the target request is built.
AM-StripKey removes the credential so it never reaches your backend
(or your backend's logs):
<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StripKey">
<DisplayName>AM-StripKey</DisplayName>
<Remove> <!-- (1)! -->
<QueryParams>
<QueryParam name="apikey"/> <!-- (2)! -->
</QueryParams>
</Remove>
<AssignTo createNew="false" type="request">request</AssignTo> <!-- (3)! -->
</AssignMessage>
<Remove>deletes parts of a message (counterpart of<Set>/<Add>).- Which query parameter to delete — by name. Nothing happens if it isn't there.
- Edit the request object. This is what gets forwarded to the target, so the key never reaches the backend, its logs, or proxies after Apigee.
Exercise it¶
HTTP/2 401
{"error": {"code": "UNAUTHORIZED", "message": "valid credentials required", "fault": "FailedToResolveAPIKey"}}
That tidy body is produced by the bundle's FaultRule + AM-Error401
(Lab 6). Without them Apigee would return its default fault:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}.
HTTP/2 200
{
"message": "orders list",
"app": "labs-app",
"developer": "you@example.com",
"cache": "miss (backend)",
...
}
That app/developer block is added by JS-ShapeResponse reading
variables VerifyAPIKey populated:
| Variable | Value |
|---|---|
verifyapikey.VA-CheckAPIKey.client_id |
the consumer key |
apiproduct.name |
labs-product |
developer.email |
you@example.com |
developer.app.name |
labs-app |
Check them in Trace — expand the VA-CheckAPIKey step and watch the
variables appear.
Experiments¶
- Header instead of query param. Change the
reftorequest.header.x-apikey, redeploy, and test withcurl -H "x-apikey: $APIKEY". Which do you prefer, and why? (Headers keep keys out of URL logs.) - Revocation.
apigeecli apps delete -o $APIGEE_ORG -t "$TOKEN" -n labs-app --email you@example.com→ the same key now 401s. Recreate the app afterwards. - Wrong product. Create an app without
--prods labs-productand confirm its key is rejected — the key must resolve to a product that covers this proxy. - Comment out
AM-StripKey, redeploy, and watch the key arrive at mocktarget in Trace's "Request sent to target" view — a concrete demonstration of why stripping matters.
Check yourself¶
1. A key is valid but the proxy returns 401 InvalidApiKeyForGivenResource. What's wrong, and where do you fix it?
The app's product doesn't include labs-proxy (or this environment). Fix
the product's proxy/env list or attach the app to the right product — no
proxy change needed.
2. Why must AM-StripKey come after VA-CheckAPIKey?
VerifyAPIKey reads the key from the query string. Strip it first and
there is nothing to read — you'd get FailedToResolveAPIKey for every
request, valid key or not.
3. Name two reasons to prefer a header over a query parameter for the key.
URLs are recorded in access logs, browser history and Referer headers;
headers generally aren't. Headers also keep the key out of shared links
and copy-pasted URLs.
4. What does continueOnError=\"true\" on VA-CheckAPIKey do to your security?
A failed verification no longer aborts the flow — anonymous requests would proceed to the backend. Never set it on gate policies.
Next¶
Lab 3 — OAuth & JWT: upgrade from static keys to short-lived tokens at the edge.