Require an API key

An API key is the first lock on an API: every client sends a key of its own on every request, and a request without a known key is refused. In G8 the key lives on a consumer, which stands for one client, and the plugin key-auth on the route reads it. This guide puts key-auth on orders-api and gives the consumer mobile-app its key. At the end, a request with the key of mobile-app reaches your backend, which learns who is calling from a header, and a request without a known key is answered 401.

Before you start

• This guide starts from orders-api as Route requests to a backend leaves it, with no other plugin. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
• The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
• The requests below call /orders/42.
• This page creates two consumers, mobile-app and partner-portal, each with a key of its own. The last answer of Check it needs the second one.
• On a route that already serves clients, do the steps in a different order: create every client's consumer and key first, steps 4 to 6, and add key-auth to the route last. From the moment key-auth is on the route, every request without a known key is refused, your own included.
• The Editor or Environment administrator role in this environment. Only a role that manages consumers and credentials can create them and see a key.

Steps

1. Open the route's Plugins tab

Open orders-api under Routes, select its Plugins tab, then Add plugin at the top right of the tab.

2. Choose key-auth

Open the Authentication category, or type key-auth in the search box. Select key-auth, then Configure. A panel with the plugin's form opens.

3. Name the header and add the plugin

Fill in two fields and leave the rest as they are.

Field	Value	Why
Header	x-api-key	The header the client sends its key in. Both the header and the query parameter are named apikey by default. This guide renames the header; the query parameter keeps its name and is read only when the header is absent.
Hide credentials	on	The key is removed before the request goes on, so your backend never sees it.

Select Add plugin at the bottom of the panel. The tab now lists key-auth, and the plugin is saved like this:

key-auth · as the console saves it

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

From now on, every request to orders-api without a valid key is answered 401. The next steps create the first key. If the route already serves clients, do steps 4 to 6 before this one.

4. Create the consumer

A consumer stands for one client, here mobile-app. Select Consumers in the menu, then New consumer. Under General, set Username to mobile-app and type a Description that says which client it is. Leave Labels and Consumer group empty.

The General section of the new-consumer form, with the username mobile-app and a description filled in.

Select Create consumer. The console opens the new consumer. The username cannot be changed later, because it is the name your backend will see.

Create partner-portal the same way.

5. Give the consumer its key

On mobile-app, select its Credentials tab, then New credential at the right of the tabs. Under General, set Credential ID to mobile-app-key-2026. The ID is not a secret, and a year in it tells a consumer's keys apart when you replace one.

Under Authentication, choose key-auth in Plugin. The fields of that plugin's credential open below. For key-auth there is one, Key.

Type the key the client will send. Treat it like a password: long and random, from a password generator, made for this one client. Show, the eye at the end of the field, shows what you typed.

The Authentication section of the new-credential form, with key-auth chosen and a key typed in.

Select Create credential. A key that another credential already carries is refused when you save, whoever it belongs to.

Give partner-portal its key the same way, with the ID partner-portal-key-2026 and a key of its own.

6. Hand the key over

Open the credential from the Credentials tab. Its Overview tab shows the Authentication card with the key masked; Show reveals it and Hide masks it again. Under a role that does not manage credentials, the key stays masked, there is no Show, and the card says: Secrets are shown only to roles that manage credentials.

Give the key to the team that runs the client the way you pass other secrets, never by mail or chat.

Check it

Send a request with the key of mobile-app in the x-api-key header, then without it, then with a made-up key, then with the key of partner-portal.

curl

curl -i -L 'https://<gateway host>/orders/42' \
  -H 'x-api-key: <the key of mobile-app>'

With the key

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.

Without a key

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".

With a key nobody has

A request whose key no credential holds is answered 401 with {"message":"Invalid API key in request"}.

With another consumer’s key

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.

What to know

• Your backend receives the consumer's username in X-Consumer-Username and the credential's ID in X-Credential-Identifier. That is how it tells clients apart.
• Once the header is named x-api-key, a key sent in the apikey header is not read, and the request is answered 401 like one without a key. The query parameter is read only when the named header is absent.
• Every consumer with a known key passes. To let only some of them in, add Allow only named clients or Allow a team by label on the same route.
• A refused request carries a WWW-Authenticate header naming apikey and the realm, key unless you set one in the Realm field of the form.

Related

• Give a client its key, and replace it: a second key beside the first, and deleting the old one.
• Authentication: consumers, credentials and consumer groups, and why people who sign in at an identity provider are not consumers.
• key-auth, Consumer and Credential in the reference.