Skip to main content

Give a client its key, and replace it

A credential is one key, or one username and password, that identifies a consumer. A consumer can hold several, and each one identifies that consumer on its own. That is how a key is replaced without a gap: the new key is created beside the old one, the client moves over, and the old key is deleted. This guide walks through the first key of mobile-app, then a second one, and deletes the first. At the end, mobile-app signs in with its new key only, and a request with the first key is answered 401.

Before you start​

  • This guide starts from orders-api as Route requests to a backend leaves it, with key-auth from Require an API key and 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 consumer the key belongs to, mobile-app, from step 4 of Require an API key. Its steps 5 and 6 create the first key the same way as steps 1 to 4 below. If you did that, start at step 5.
  • 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.
  • The Editor or Environment administrator role in this environment. Only such a role sees a key and can create, change or delete a credential.

Steps​

1. Open the consumer's Credentials tab​

Open mobile-app under Consumers and select its Credentials tab. A consumer without credentials says No credentials yet. Select New credential at the right of the tabs.

2. Name the credential​

Under General, set Credential ID to mobile-app-key-2026. Letters, digits, dots, hyphens and underscores are allowed, and the ID cannot be changed later. The ID is not a secret, and a year in it tells a consumer's keys apart when you replace one. Your backend receives it in X-Credential-Identifier with every request this key signs in.

Name and Description, in the same section, are for the next person who opens the credential. Labels are for grouping and filtering in the console and change nothing about traffic.

The General section of the new-credential form, with the ID mobile-app-key-2026 filled in.

3. Choose the plugin, type the key and create the credential​

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. From now on, a request that sends this key in the x-api-key header belongs to mobile-app.

4. Hand the key over, and read it back later​

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.

The Overview tab of a credential, with the Authentication card and the masked key.

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

5. Give the consumer a second key when the first is to be replaced​

Back on the Credentials tab, which now lists mobile-app-key-2026, select New credential again. Fill in the form as for the first key, with a new ID and a new key.

FieldValue
Credential IDmobile-app-key-2027
Namemobile-app key, 2027 rotation
DescriptionValid beside the previous key until every app build has moved over
Pluginkey-auth
KeyA new key from the password generator.

Select Create credential. An ID the consumer already has is refused, so each key gets an ID of its own. Both keys now identify mobile-app. Hand the new key to the team that runs the client; the first one goes on working until you delete it. A key cannot be edited in place, which is why the new one is a second credential.

The Credentials tab of mobile-app, listing both credentials.

The second credential is saved like this:

credential · as the console saves it
{
  "id": "mobile-app-key-2027",
  "name": "mobile-app key, 2027 rotation",
  "desc": "Valid beside the previous key until every app build has moved over",
  "plugins": {
    "key-auth": {
      "key": "<secret>"
    }
  }
}

6. Delete the first key once no request uses it​

Your backend's log tells you when the first key is out of use: no request carries mobile-app-key-2026 in X-Credential-Identifier any more. If the backend is not yours, ask its team to check. For a key that leaked, do not wait: whoever holds it can go on sending it. Delete it as soon as the client sends the new key.

On the Credentials tab, open the menu at the end of the mobile-app-key-2026 row and select Delete credential. The dialog names the credential and its consumer. Confirm with Delete credential. In a protected environment the dialog first asks you to type the credential's ID.

The delete dialog for the credential mobile-app-key-2026.

Check it​

Send a request with the new key. Then send one with the first key, once before step 6, while both keys exist, and once after it.

curl
curl -i -L 'https://<gateway host>/orders/42' \
  -H 'x-api-key: <the new key of mobile-app>'
With the new key
A request with the new key is answered 200: your backend receives the consumer's username in X-Consumer-Username and this credential's ID in X-Credential-Identifier.
With the first key, before you delete it
The first key, mobile-app-key-2026, signs in as the same consumer and is answered 200 too; your backend tells the two apart by X-Credential-Identifier: mobile-app-key-2026.
With the first key, once deleted
Once the first key's credential is deleted, a request with that key is answered 401 with {"message":"Invalid API key in request"}, and the new key goes on answering 200.

What to know​

  • Your backend receives the credential's ID in X-Credential-Identifier beside the consumer's username in X-Consumer-Username, so its log shows which of a consumer's keys each request used.
  • One plugin per credential. A consumer that signs in with a key and also with a password holds two credentials.
  • Replace a key with a second credential, as above. The copies of the client that still send the old key keep working while they move over.
  • Deleting a credential cannot be undone, and requests that use it fail from the next one.
G8 dev