key-auth

Authenticates consumers with an API key sent in a header or query parameter.

Category AuthenticationAdd it to Route, Service, Global rule, Plugin configEngine plugin key-authPriority 2500Needs a Consumer with a key-auth Credential

What it does

key-auth identifies the caller by an API key. The key lives on a consumer, as one of its credentials. The plugin on the route reads it from the header named under Header. When that header is absent, it reads the query parameter named under Query. Both are apikey unless you change them.

A request with a known key passes as that consumer, and the backend receives the consumer's username in X-Consumer-Username. A request with no key, or with one no credential holds, is answered 401. Every consumer with a known key passes. To let only some of them through, add consumer-restriction or acl to the same route.

When to use it

• The first lock on an API: one key per client, created on its consumer, that the client sends on every request.
• Telling callers apart further down the line: the backend reads X-Consumer-Username, and plugins that limit or allow by consumer act on the name the key resolves to.
• Keys that must not reach the backend: Hide credentials removes the header or query parameter once the key is checked.
• Letting requests without a key through as a named consumer, under Anonymous consumer.

Not for a username and password a person types — see basic-auth (Authenticates consumers with HTTP Basic credentials) or signed tokens that expire or carry claims — see jwt-auth (Authenticates consumers with a JSON Web Token they present).

Guides

Pages that walk through a job with key-auth, step by step.

• Require an API keyPut key-auth on a route and give the first client its key.

Set it up

Read the API key from a header and keep it out of the upstream request

Set Header to x-api-key and turn on Hide credentials.

The console's Add plugin panel, filled with this example.

key-auth · as the console saves it

{
  "header": "x-api-key",
  "hide_credentials": true
}

What you will see

• A request whose x-api-key header carries the key of mobile-app is answered 200; the header is removed before the request reaches the backend, which receives X-Consumer-Username: mobile-app instead.
• A request that carries the key neither in that header nor in the apikey query parameter is answered 401 with {"message":"Missing API key in request"} and WWW-Authenticate: apikey realm="key".
• A request whose key no credential holds is answered 401 with {"message":"Invalid API key in request"}.
• The key of any other consumer is let in too: a request with the key of partner-portal is answered 200, and the backend receives X-Consumer-Username: partner-portal.

More scenarios

Give a consumer its API keycredential

One of a consumer's credentials; the client sends the key where the route's key-auth reads it, here the x-api-key header its Header names.

Set Key to <secret>.

key-auth credential · as the console saves it

{
  "key": "<secret>"
}

What you will see

• A request that sends this key in the x-api-key header the route's key-auth reads is answered 200; the backend receives the consumer's username in X-Consumer-Username and this credential's ID in X-Credential-Identifier.
• A request with no key is answered 401 with {"message":"Missing API key in request"}, and one whose key matches no credential with {"message":"Invalid API key in request"}.

Things to know

• Query — The query parameter is read only when the named header is absent: a wrong key in the header is refused even when the right one is in the query.
• Header — Once Header is x-api-key, a key sent in the apikey header, the default name, is not read: the request is answered 401 as one with no key.
• Hide credentials — On, the key is removed before the request reaches the backend, which still receives the consumer's username in X-Consumer-Username.
• Hide credentials — Off, the key travels on to the backend in the header or query parameter it arrived in.
• Key — A credential whose key is empty authenticates any request that sends the header or query parameter with an empty value. The engine reads an empty key as a key that is there.
• Realm — A refused request carries a WWW-Authenticate header naming apikey and your Realm, key unless you set one.
• Anonymous consumer — While this names an existing consumer, a request with no credential or a wrong one passes as that consumer instead of being refused. A name that belongs to no consumer refuses them with 401.
• Header — Left empty, the key is read from the header apikey; a request without that header may carry the key in the query parameter Query names.

Settings

The fields as the console shows them, section by section.

Headerheaderstringdefault apikey

Queryquerystringdefault apikey

The request argument the key may arrive in. Read only when the named header carries no key.

Hide credentialshide_credentialsbooleandefault false

Realmrealmstringdefault key

The realm sent in WWW-Authenticate when a request is refused. No double quotes or backslashes.

1 to 128 characters ·

pattern

^[ -!#-[\]-~]+$

Anonymous consumeranonymous_consumerstring

at least 1 character · letters, digits, hyphens and underscores up to 256 characters, or a $secret:// or $env:// reference

pattern

^([$]secret://.+|[$][Ee][Nn][Vv]://.+|[a-zA-Z0-9_-]{1,256})$

Credential

What each consumer's credential for key-auth carries.

KeykeystringRequired

The API key clients send, a long random string only that client knows, in the header or query parameter the plugin's settings name. A key that another credential already carries is refused, whoever it belongs to. Stored on the engine and shown only to roles that manage this object.

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.