API key provider
type: api_key authenticates a request by matching a presented key against a static list of
keys configured on the gateway. Each key entry carries a holder name and optional scopes.
How it works01
The key is read from
header_name(defaultX-API-Key). If that header is absent andquery_paramis configured, the key is read from that query-string parameter instead.If no key is found, the result is Unauthenticated.
The key is looked up in the configured
keyslist. An unknown key yields Failed (Invalid API key).On a match, the principal is built as:
id=apikey:<entry name>name= the entry'snameroles=["api_consumer"](fixed)scopes= the entry'sscopesif the entry has a
rate_limit, it is attached as a principal attribute namedrate_limit.
Every API-key principal is given the single role api_consumer. The key entries' scopes are
the lever for authorization (require_scopes and Rhai
has_scope), since per-key roles are not configurable.
Configuration02
| Key | Type | Default | Description |
header_name | string | X-API-Key | Header to read the key from. |
query_param | string | none | Query-string parameter to read the key from when the header is absent. |
keys | list of key entries | [] | Accepted keys. |
external_validator | string | none | Not wired — see callout below. |
Key entry
Each item in keys:
| Key | Type | Default | Description |
key | string | — | The API key value. Required. |
name | string | — | Human-readable name for the key holder; used in the principal id and name. Required. |
scopes | list of strings | [] | Scopes granted to this key. |
rate_limit | integer | none | Per-key requests/minute. Surfaced as the principal attribute rate_limit. |
external_validator is accepted by the configuration schema but is not currently used: keys
are only matched against the static keys list. There is no remote key-validation call. The
rate_limit value is exposed as a principal attribute but is not itself enforced by this
provider — wire it through a rate-limit middleware if you want enforcement (see
Middleware).
Caching note03
A successful API-key match is cached by the auth-gateway only when the request also carries an
Authorization header (or a TLS client CN). Keys presented solely in a custom header such as
X-API-Key, or in a query parameter, are not cached and are re-validated on each request — a
cheap in-memory lookup. See token caching.
Example04
auth_providers:
partner-keys:
type: api_key
header_name: X-API-Key
query_param: api_key
keys:
- key: "${PARTNER_A_KEY}"
name: partner-a
scopes: ["read", "write"]
rate_limit: 600
- key: "${PARTNER_B_KEY}"
name: partner-b
scopes: ["read"]
auth:
default_provider: partner-keys
global_enforce: trueSee also05
Authorization — using key scopes in
require_scopesand rules.