Anonymous Consumers
Let unauthenticated callers through an authenticated route under a named consumer identity, so they can be rate limited and attributed like any other consumer.
An anonymous consumer lets a route that requires authentication also serve callers who present no credential. Instead of rejecting the request, the authentication plugin attaches a consumer you nominate, and the request continues as that consumer.
The point is not to disable authentication. It is to give unauthenticated traffic an identity — because everything the gateway can do per consumer (rate limits, quotas, logging attribution, plugin configuration) then applies to it.
How it works
Configure an anonymous_consumer on the authentication plugin, naming an existing consumer. When a request arrives without valid credentials, the plugin resolves it to that consumer rather than returning 401.
Supported by key-auth (opens in Plugin Hub docs), basic-auth (opens in Plugin Hub docs), jwt-auth (opens in Plugin Hub docs), and hmac-auth (opens in Plugin Hub docs).
Because the request resolves to a real consumer, per-consumer behaviour applies to it as it would to any other — rate limiting, plugin configuration and logging attribution all key off the anonymous consumer. The gateway also forwards X-Consumer-Username carrying the anonymous consumer's name, so the upstream can tell anonymous traffic apart without re-deriving it. An authenticated request additionally carries X-Credential-Identifier with the ID of the credential that matched; an anonymous one does not, because no credential was presented.
Quotas
The usual arrangement is a strict quota on the anonymous consumer and a generous one on authenticated consumers — see Configure Rate Limiting.
Once an anonymous consumer exhausts its quota, further anonymous requests are rejected until the next rate-limiting window. Authenticated consumers are unaffected, which is the property that makes this useful: a surge of unauthenticated traffic degrades only itself.
When to use it
- Freemium or trial access. Serve a limited slice of an API without registration, and reserve the rest for authenticated users.
- Public and private data on one route. Anonymous callers reach the public subset; the same route serves more to an authenticated consumer.
- Demo and sandbox environments. Let an evaluator try the integration before there is an account to issue a credential against.
Give the anonymous consumer its own plugin configuration and permissions rather than reusing an existing consumer's. Anything the nominated consumer can reach becomes reachable without credentials, so the blast radius of a misconfiguration is exactly that consumer's access.