Credential

Credentials carry the keys and passwords a consumer signs in with.

In the console CredentialsBelongs to a consumerEngine resource credential

What a credential is

A credential is what a consumer signs in with, for one authentication plugin: an API key, or a username and password. It belongs to one consumer. When the plugin on the route finds it in a request, the request belongs to that consumer. Your backend receives the consumer's username in X-Consumer-Username and the credential's ID in X-Credential-Identifier.

A consumer can hold several credentials, and each one signs in as that consumer on its own. That is how a key is replaced without a gap. Authentication shows where credentials sit between the client and your backend.

When to use it

• Give a client its API key: a credential on the client's consumer, holding the key the client sends.
• Replace a key without a gap: a second credential beside the first until every copy of the app sends the new key, then delete the first.
• Tell which of a consumer's keys a request used: your backend receives the credential's ID in X-Credential-Identifier.
• Take one key out of use, for example one that leaked, while the consumer's other keys go on working.

Guides

Pages that walk through a job with a credential, step by step.

• Accept signed tokensPut jwt-auth on a route and give the client the credential that checks the tokens it signs.
• Ask for a username and passwordPut basic-auth on a route so that a client signs in with a username and password, and a browser asks for them.
• Give a client its key, and replace itCreate a key, hand it over, and replace it later without a gap.
• Require an API keyPut key-auth on a route and give the first client its key.

Set it up

Give a consumer its first API key

The client sends the key where key-auth on the route reads it, here the x-api-key header.

Under General set Credential ID to mobile-app-key-2026. Under Authentication fill Plugin as in the JSON below.

credential · as the console saves it

{
  "id": "mobile-app-key-2026",
  "plugins": {
    "key-auth": {
      "key": "<secret>"
    }
  }
}

What you will see

• A request that carries this key where key-auth on the route reads it is answered 200, and your 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 no credential holds with {"message":"Invalid API key in request"}.

More scenarios

Give a consumer a second API key while the first one is rotated

The earlier key stays valid beside it until its credential is deleted, and both sign in as the same consumer.

Under General set Credential ID to mobile-app-key-2027, set Name to mobile-app key, 2027 rotation and set Description to Valid beside the previous key until every app build has moved over. Under Authentication fill Plugin as in the JSON below.

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

What you will see

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

Things to know

• Credential ID — Your backend receives it in X-Credential-Identifier with every request the credential signs in, beside the consumer's username in X-Consumer-Username, so its log shows which of a consumer's keys each request used.
• Plugin — One plugin per credential: a consumer that signs in with a key and also with a password holds two credentials.
• With key-auth, a key that another credential already carries is refused when you save, whoever it belongs to.
• AdviceReplace a key with a second credential, as in the steps, rather than by typing a new key into the first one: the copies of the app 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.

Plugins that carry a credential

The one key under plugins is one of these plugin names, and its value is what that plugin's Credential section lists: basic-auth, hmac-auth, jwe-decrypt, jwt-auth, key-auth, ldap-auth, ldap-auth-advanced.

Settings

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

General

Credential IDidstring or integerRequired

Letters, digits, dots, hyphens and underscores, up to 64 characters. The ID cannot be changed later. Names the object in the engine.

string 1 to 64 characters or integer at least 1 or string 15 to 128 characters · one of 2 patterns

patterns

^[a-zA-Z0-9-_.]+$^[a-zA-Z0-9-_]+/credentials/[a-zA-Z0-9-_.]+$

Namenamestring

1 to 256 characters

Descriptiondescstring

up to 256 characters

Labelslabelsobject

Key and value pairs of your own, for grouping and filtering. They change nothing about traffic. An object whose keys are any name, each with a string as its value.

Authentication

One authentication plugin per credential. Its fields come from the plugin's credential schema.

PluginpluginsobjectRequired

Exactly one plugin, named by its key, with the fields that plugin's credential takes.

exactly 1 key