Consumer

Consumers identify the callers of your APIs; their credentials live under each consumer.

In the console ConsumersEngine resource consumer

What a consumer is

A consumer stands for one client of your APIs, for example the mobile app. It signs in with its credentials, usually an API key. An authentication plugin on the route, usually key-auth, finds the credential a request carries. From then on the request belongs to that consumer, and your backend receives its Username in X-Consumer-Username.

The consumer decides what happens next. Its Labels are read by acl, its own plugins run on its requests, and its consumer group adds plugins shared with others. Authentication shows how the pieces fit together.

When to use it

• Give each app, partner or team that calls your APIs a consumer of its own, so your backend and the plugins on a route can tell them apart.
• Give one client its own limit, whatever route it calls, with a plugin on the consumer.
• Let a route in by team rather than by name, with a label on the consumer that acl reads.
• Replace a client's key without a gap: the consumer holds the old and the new key side by side.

Not for people who sign in at your identity provider, for example staff in front of an internal web application — see openid-connect (Authenticates users against an OpenID Connect provider).

Guides

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

• Allow a team by labelLet consumers through by a label they carry, so a route stays as it is when the team changes.
• Require an API keyPut key-auth on a route and give the first client its key.
• Limit one client wherever it callsGive one consumer its own limit, counted over every route that asks for its key.

Set it up

Set up the mobile app with its own request limit

Its keys are created in the Credentials tab; the limit counts the app's requests on every route that asks for its key, in one count.

Under General set Username to mobile-app, set Description to The iOS and Android apps, which call under one consumer name and fill Labels as in the JSON below. Once it is created, open its Plugins tab and add limit-count with its settings from the JSON below.

consumer · as the console saves it

{
  "username": "mobile-app",
  "desc": "The iOS and Android apps, which call under one consumer name",
  "labels": {
    "team": "mobile"
  },
  "plugins": {
    "limit-count": {
      "count": 600,
      "time_window": 60,
      "key": "consumer_name",
      "rejected_code": 429
    }
  }
}

What you will see

• A request with the key of mobile-app is answered 200 with X-RateLimit-Limit: 600: the consumer's own limit-count counts it, though the route carries no limit of its own.
• The same key on a second route that asks for it is counted in the same 600: after one request on each route, the answer carries X-RateLimit-Remaining: 598.
• Your backend receives the request with the consumer's username in X-Consumer-Username.
• A request without a key is answered 401 with {"message":"Missing API key in request"}.

More scenarios

Label the payments team's consumer for a route that lets one team in

acl on the route reads the label of the consumer itself; a label on its consumer group is not read.

Under General set Username to payments-app and fill Labels as in the JSON below.

consumer · as the console saves it

{
  "username": "payments-app",
  "labels": {
    "team": "payments"
  }
}

What you will see

• On a route whose acl lets the payments team in, a request with the key of this consumer is answered 200 by your backend.
• A consumer with no team label of its own is answered 403 with {"message":"The consumer is forbidden."}, even when its consumer group is labelled team payments: acl reads the labels of the consumer itself.

Things to know

• Username — Your backend receives it in X-Consumer-Username on every request the consumer signs in with.
• AdviceTo rename a consumer, create one under the new name with credentials of its own, move the client over, then delete the old consumer.
• Labels — Read from the consumer itself: acl does not read a label on the consumer's consumer group, so a consumer with no label of its own is refused by an allow list.
• Labels — A consumer on several teams carries them in one value, separated by commas, for example ops,payments. acl lets it through when any one of them is listed.
• Plugins — Where a route carries the same plugin, the consumer's copy runs and the route's does not. Failing that, the copy on its consumer group runs. A consumer with a limit of 2000 is counted by it on a route whose own limit is 100.
• Plugins — A limit-count on the consumer keeps one count for it across every route that asks for its key, not one on each route.
• Deleting a consumer deletes its credentials with it: clients that sign in with them are refused from the next request, and it cannot be undone.

Settings

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

General

UsernameusernamestringRequired

Letters, digits, underscores and hyphens. The username is the identity of the consumer and cannot be changed later.

1 to 256 characters ·

pattern

^[a-zA-Z0-9_\-]+$

Descriptiondescstring

up to 256 characters

Labelslabelsobject

Key and value pairs of your own, for grouping and filtering. The acl plugin on a route reads them to let this consumer through or refuse it. An object whose keys are any name, each with a string as its value.

Consumer groupgroup_idstring or integer

Plugins of the group apply to this consumer as well.

string 1 to 64 characters or integer at least 1 · letters, digits, dots, hyphens and underscores

pattern

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

Plugins

Plugins on this consumer are managed in the Plugins tab once the consumer exists. It signs in with credentials, which are created in the Credentials tab; the Plugins tab offers no plugin that reads a credential, and a plugin added here runs only after the consumer has been identified.

Pluginspluginsobject

The plugins of this consumer, keyed by plugin name. The engine runs them by their priority, not by the order they are written in.