Apache APISIX API key authentication with key-auth

When Apache APISIX API key authentication with key-auth fits your API

Choose key-auth when your goal is to identify which client is calling an API using a static credential checked at the gateway. It suits partner integrations, internal services and developer access where each caller is a consumer object in APISIX holding its own key, and where you need per-client rate limits or access rules without running an identity provider. The key-auth plugin reads the key from the apikey header by default and gives header precedence over query parameters, so the first decision is whether your clients can send a header at all. Apache APISIX 3.19.0, released on September 28, 2026, is the version context for the settings described on this page. Confirm the plugin behavior on the release you will run before you write client documentation.

Be clear about what key-auth does not do. A key identifies a consumer application, not a person, so it carries no user identity, no roles from a directory and no scopes that change per user. A key does not expire by default either, so any lifetime, rotation schedule or revocation process must be designed and operated by your team. If your upstreams need to know who the end user is, or if tokens must be short-lived and verified against a signing key, a token-based method such as the JWT or OpenID Connect plugins is the better fit. Those options are covered on sibling pages of this section.

Before you commit, ask three questions. Who will issue keys, and through which workflow, since the Admin API can create consumers and credentials but someone must own that process. How long a leaked key stays usable, and whether you can rotate it without breaking active clients. And whether any traffic should be allowed without a key at all, which is where the anonymous consumer option matters. Write the answers down as requirements. They determine the consumer model, the storage of key material and the rotation runbook that the rest of this page sets out. Also confirm with your security team how keys will be classified, because a static bearer-style credential usually needs stricter handling than its size suggests.

Key-auth configuration options and when each fits

This table compares the key-auth settings that shape how API keys are read, protected and tolerated at the gateway, against the callers each setting usually serves. Read each row as a decision: the default works for most internal callers, while hiding credentials and anonymous access need deliberate choices for partner and public traffic. Confirm exact parameter names and defaults against the key-auth plugin reference before writing configuration.

Setting	What it controls	Best fit	What to confirm
Header default (apikey)	Key read from the apikey request header when no other location is set	Internal services and partner clients that can send a custom header	Header name and default value in the key-auth plugin reference
Query parameter	Key read from a URL query parameter so simple callers can pass it in the request line	Legacy clients or webhooks that cannot set headers	Whether query keys appear in gateway access logs and proxy logs you retain
Header priority over query	Which location wins when a request carries a key in both places	Migrations where old and new clients send keys differently	Precedence rules and how mismatched duplicates are rejected
hide_credentials	Removes the key from the request before it reaches the upstream	Partner APIs and upstreams that must not receive or log caller secrets	Whether the upstream still needs a derived identity header from the gateway
Keep credential visible	Key is forwarded to the upstream unchanged	Upstreams that validate the key themselves during a transition	Who owns key validation and how keys are protected in upstream logs
anonymous_consumer	Lets unauthenticated requests pass as a designated consumer with its own limits	Public or read-only traffic that needs a low, separate quota	That the anonymous consumer exists, its rate limits and which routes allow it
No anonymous consumer	Requests without a valid key are rejected at the gateway	Partner APIs and private services where every caller must be known	Error responses returned to clients and monitoring of rejected requests
Encrypted storage and references	Keys stored encrypted in etcd or loaded from environment or Vault references	Production clusters where keys must not sit in plain configuration	Data encryption settings and the reference syntax in the plugin documentation

How consumers and keys map to clients

In APISIX, a consumer is the record that identifies a client, and its key-auth credential is how that client proves who it is. Getting this mapping right decides whether you can revoke one partner without touching the others and whether logs tell you which caller did what.

One consumer per application or partner

Create a separate consumer for each application, service or partner that calls the gateway. Each consumer carries its own key-auth credential, so a rotation or revocation affects only that client. Ask your team to list every caller before building, because a consumer that represents several teams becomes the shared-key problem in a different form. Confirm the naming convention with the owners who will administer the Admin API.

One key per consumer

Issue one active key-auth key per consumer as the default pattern. A single key per client keeps the link between a request and its caller unambiguous in access logs. If a client needs to rotate without downtime, plan for a second key during the overlap window instead of sharing one key across clients. Check how your logging pipeline records the consumer name when a request authenticates.

Why shared keys block revocation

When several clients use the same key, revoking it cuts off every one of them at once. The team then has to coordinate a new key with each client before traffic recovers, which turns an access decision into an outage. Shared keys also erase attribution, since the gateway can only record that the key was used. Treat any shared key found during an audit of the consumer list as a finding to correct.

What the consumer record holds

A consumer record holds a unique username, the key-auth credential, and any plugin configuration that applies to that client, such as rate limits or labels. Consumer groups can share limits across several consumers when that matches your policy. Record an owner, a contact and a review date in your own change process, since APISIX does not define those fields for you. Confirm which fields your Admin API workflow stores outside the gateway.

Tying consumers to the consumer design

Consumer modeling covers more than key-auth, including plugin precedence, credential types beyond keys and lifecycle automation through the Admin API. Decide the consumer model for the whole gateway before issuing keys, so that key-auth follows the same naming, ownership and removal rules as other authentication methods. Review the consumer design topic before creating the first production consumer.

Where key-auth keys are stored and how Vault references work

The storage decision comes first: whether key-auth consumer keys are encrypted at rest in etcd. APISIX stores AES-encrypted key values in etcd when data encryption is enabled, so a copy of the etcd data directory or a backup does not expose plaintext credentials. Confirm that data encryption is turned on in your APISIX configuration before any consumer is created, and check how the encryption key itself is supplied and rotated, because that key protects every encrypted value. Also confirm who can read etcd snapshots, since encryption does not replace access control on the etcd cluster.

If you do not want key material written into the Admin API payload or the configuration store at all, key-auth can reference a value instead. An environment variable reference using $env:// resolves the key from the gateway process environment at runtime, which fits containerized deployments where the orchestrator injects secrets. A $secret:// reference resolves the key from a HashiCorp Vault KV path. Confirm the exact reference syntax and KV path format against the key-auth plugin documentation for the APISIX version you deploy, and test how the gateway behaves when a referenced value is missing.

The Vault choice carries licensing and product factors that belong in the secrets decision. HashiCorp announced on August 10, 2023 that future releases would move to the Business Source License 1.1, and the Vault LICENSE file names IBM as licensor for Vault 1.15.0 or later. IBM completed its acquisition of HashiCorp on February 27, 2025. OpenBao is a community fork under MPL-2.0, but its migration guide was tested only against Vault 1.14.1 community edition, not Vault Enterprise. Ask your legal and procurement teams which edition and license terms apply to you, and confirm with your DeployOpen scope whether the reference works with the secrets product you choose, including the backend and high availability design your team will run.

Setting up key-auth in an APISIX route

This sequence takes a route from no authentication to one that issues a consumer key, stores it safely, rejects bad callers, strips the credential before upstreams see it, and admits anonymous traffic under its own limits. Each step ends with a check so the team knows the gateway behaves as designed before any client is onboarded.

Confirm data encryption is enabled
Before any consumer key is written, the platform team turns on APISIX data encryption so that key-auth credentials are stored encrypted in etcd. Set the encryption keys in the APISIX configuration file for your deployment, then restart or reload according to your deployment mode. Confirm the setting with your own deployment documentation and test it in a non-production environment first. Done means a test credential written through the Admin API does not appear in plain text when you read the raw value from etcd.
Create the consumer for the calling application
Create one consumer per application or partner that will call the API, using the Admin API or your configuration-as-code tooling. Give the consumer a clear name and a label that identifies the owning team, because consumer identity drives logging, limits and later access decisions. Do not reuse a consumer across unrelated clients. Done means the consumer appears in the Admin API listing with its name and labels, and no key has been attached yet.
Store the key through a reference, not a literal
Generate a long random key outside the gateway and place it in an environment variable on the APISIX nodes, or in a HashiCorp Vault KV secret that the gateway can read. Reference it in the consumer's key-auth configuration with the $env:// or $secret:// form instead of pasting the value. The reference keeps the credential out of route exports and version control. Confirm with your platform team how the Vault token and paths are managed. Done means the consumer's key-auth entry shows the reference, and a request-free read of the consumer does not reveal the value.
Attach key-auth to the route
Enable the key-auth plugin on the target route, keeping the default apikey header unless your client standard requires another location. Leave the header-over-query precedence in place and decide whether any client needs the query parameter, since query strings often reach access logs. Save the route and confirm it lists key-auth among its plugins. Done means the route is saved with key-auth enabled and no other route changed.
Set hide_credentials and anonymous_consumer
Set hide_credentials to true so APISIX removes the key from the request before it reaches the upstream, which keeps the credential out of backend logs. If some traffic should pass without a key, define an anonymous consumer with its own lower rate limits and set anonymous_consumer on the route to that consumer name. Review the anonymous limits with the owning team before enabling them. Done means an upstream test service records no apikey header on an authenticated call, and the anonymous consumer exists with its limits.
Test valid, missing, wrong and anonymous requests
Send four test calls to the route: one with the correct key, one with no key, one with an incorrect key, and one with no key where anonymous access is intended. Expect success for the valid key, a 401 for the missing and wrong keys, and the anonymous consumer's limits applied for the last call. Record the status codes and the consumer identity in the gateway logs for each case. Done means all four results match the expected outcomes and the logs show the correct consumer name.
Rotate keys without downtime
To rotate, have the consumer hold two keys briefly by creating a second key-auth credential or updating the referenced secret, then move the client to the new key and remove the old one after the client confirms. Make the change in the secret store first so the gateway reads the new value on its next lookup. Test the rotation on a staging route before doing it in production. Done means a call with the new key succeeds, the old key returns a 401, and no client saw an outage during the change.

Security risks in static API key designs

A static API key is a bearer credential: whoever holds it can call the route until someone revokes it. The risks below come from how keys are transported, stored, scoped and administered, and each one maps to a setting or process you control at the APISIX gateway.

Keys leaking through logs and URLs

When a key travels in a query string, it can end up in access logs, proxy logs, browser history and monitoring tools. Prefer the apikey header, which the key-auth plugin reads by default, and confirm that your log format does not record full request headers or query strings for routes that use key-auth. Check what your upstream, load balancer and observability stack capture before go-live, since the gateway is only one place the value passes through.

Keys sent over plain HTTP

A key sent over an unencrypted connection can be read by anyone on the network path. Make TLS a requirement on every route that accepts a key, and confirm that HTTP listeners either redirect or reject key-bearing requests. Certificate and listener configuration belongs in the gateway hardening work, so this card only sets the rule that the key-auth route must not answer on cleartext.

No built-in expiry on static keys

A key-auth consumer key does not expire on its own. Without a rotation policy, a key copied once from a developer laptop or an old partner integration stays valid indefinitely. Decide a rotation interval per consumer, record who owns each key, and plan for a second key so that rotation can happen without downtime. Ask your team how a retired key will be found and removed from the Admin API.

One key shared across partners

When several partners or applications use the same key, you cannot tell their traffic apart, limit each one separately or revoke one without breaking the others. Create one consumer per application or partner, each with its own key, so that attribution in logs and rate limits stay accurate. A shared key is also hard to rotate because every party must change at once.

Admin API that holds consumer records

The consumer records and their key values sit behind the Admin API. Anyone who can call that API can read, create or disable consumers, so access to it is as sensitive as access to the keys themselves. Restrict the Admin API to a management network, change its default admin key, and confirm which accounts can call it. The Admin API listens on port 9180 in traditional mode, so confirm it is not reachable from client networks.

Questions teams ask before implementing key-auth

What drives the cost of a key-auth implementation?

The main drivers are the number of consumers, the number of routes that need the key check, the secrets storage choice, and how much testing the rollout requires. Each consumer adds onboarding, key issuance and a test case, so a gateway serving a few internal services costs far less to set up than one issuing keys to hundreds of partners. Storage matters because encrypting keys in etcd and loading them from a secrets backend add configuration and access work. Ask any partner for a quote that lists these items separately, with one-time build work (design, configuration, migration of existing keys, testing) shown apart from recurring work (key rotation support, upgrades, monitoring). Any figure must come from the written scope, not from a rate card.

How long does a key-auth implementation take?

Duration depends on scope, so no fixed number applies to every gateway. The clearest drivers are the size of the route inventory, whether existing clients must move to new keys without downtime, and how many secrets backends must be integrated. A scoped engagement should state its timeline in the written agreement, including the phases for design, build, testing, parallel running and cutover. If a proposal gives a duration without a list of included routes and consumers, ask for that list before comparing offers.

What does our team need to provide before the work starts?

The work needs a route inventory, a list of the consumers that will call each route, and a named owner for each key or client application. It also needs access to the secrets backend, such as a HashiCorp Vault or OpenBao KV path, with rights to create and read the secret references APISIX will use. Your team should also confirm the environments where APISIX will run, the etcd or standalone mode choice, and who approves changes to the Admin API. Missing owners are the most common reason key rotation stalls after go-live.

Can our own team implement key-auth without a partner?

Yes, a capable platform team can configure key-auth in APISIX, since the plugin is documented and the configuration keys are few. The harder parts are consumer design, safe key storage, hiding credentials from upstreams, anonymous consumer limits, and a rotation process that keeps old and new keys valid during the change window. Teams that lack Lua or APISIX operations experience, or that must show audit evidence to an assessor, often choose a fixed-scope partner for the design and testing phases and keep operations in-house. Confirm with your own engineers whether they can own the Admin API, etcd and the secrets integration after handover.

Where do key-auth keys go wrong in production?

The most common failures are keys sent in query strings where they appear in logs, upstreams receiving credentials they do not need, and keys stored in plain configuration instead of an encrypted or referenced form. Rotation failures also occur when a consumer is changed without an overlap period, causing outages for partners. Anonymous consumers can be misconfigured so unauthenticated traffic receives the same limits as trusted clients. Test each route for denial with a missing key, an expired key and a key from another consumer before rollout.

When is key-auth the wrong choice?

Key-auth suits server-to-server calls where a long-lived secret can be issued, stored and rotated by the client owner. It is a weaker fit when callers need to carry user identity or scopes, when tokens must expire quickly, or when you need to prove that the request body was not altered. In those cases, jwt-auth fits tokens issued by your own services, hmac-auth fits partner request signing, and the openid-connect plugin fits delegated access through an identity provider such as Keycloak or Microsoft Entra ID. Choose the method from the trust model first, then compare the operational cost of each.

Does key-auth help with compliance evidence?

Key-auth can support evidence for access control and logging, but it does not make a system compliant by itself. Assessors will look at how keys are issued, stored, rotated and revoked, and whether access decisions are logged. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue the audit reports and attestations. Ask your assessor early which evidence they expect for consumer onboarding and key rotation.

Limits to confirm in your environment

The key-auth behaviors below depend on your APISIX version, your etcd setup and your Vault edition and policies. Confirm each one against the vendor documentation or in a test environment before you write key-handling rules into your runbooks.

Query parameter behavior

Key-auth reads the apikey header first and falls back to a query parameter when the header is absent. Confirm on your exact APISIX version whether the query parameter is accepted, whether the header takes priority in your build, and whether query keys appear in access logs. Keys in URLs are often recorded by proxies and monitoring tools, so decide whether to allow the query location at all. Test with a sample request on a staging route.

Anonymous consumer limits

Anonymous consumers let unauthenticated traffic reach a route under its own rate limits. Confirm how the anonymous consumer interacts with other plugins on the route, including whether your limit plugins key on the consumer name or the client IP, and whether the anonymous consumer can reach routes you meant to protect. Run a load test that sends requests without a key and check that the lower limit actually applies.

Encryption settings on etcd

Stored keys are encrypted only when data encryption is enabled in your APISIX configuration. Confirm the encryption key settings in your deployment, check how the key is supplied to each gateway node, and verify that a stored consumer credential is not readable in plain text in etcd. Also confirm who can read etcd snapshots, since backups carry the same data.

Vault KV version and access policy

The $secret:// reference reads from a HashiCorp Vault KV path, and the KV engine version determines the path format the gateway must use. Confirm which KV version your Vault runs, create a read-only policy scoped to the gateway's consumer paths, and test that the gateway token cannot read other secrets. Confirm how token renewal is handled so the gateway does not lose access silently.

Vault edition and license features

Vault Community Edition and Vault Enterprise differ in which features need a license applied to the cluster. Confirm which edition your organization will run and whether the storage, replication or audit features you plan to rely on require Enterprise. Ask HashiCorp or your reseller for current terms, since licensing and pricing change. If you consider OpenBao, confirm its tested scope before you assume compatibility.

How DeployOpen scopes and delivers key-auth

DeployOpen plans, implements, hardens, documents and supports Apache APISIX key authentication inside your own infrastructure. We start from a written scope covering your consumers, routes, key storage and rotation process, so the key-auth design is agreed before any gateway configuration changes.

How we scope

Inventory which routes and upstream services need API key checks, and which may stay anonymous
Define consumers per application or partner, with one key per consumer and documented owners
Agree header or query placement, hide_credentials behavior and anonymous_consumer limits in writing

How we build

Configure key-auth on test routes first, then test valid, missing, invalid and rotated keys
Set up encrypted key storage and $env:// or $secret:// references to your secret manager, confirming supported versions
Build a rotation runbook and test overlapping old and new keys so clients switch without downtime

How we hand over

Deliver route, consumer and plugin configuration as versioned files with a record of design decisions
Document the rotation procedure, revocation steps and the Admin API calls your team will repeat
Run a handover session where your engineers rotate a test key and check the gateway logs

How we support

Offer ongoing upgrades, patching and key-auth reviews as a retainer after the fixed-scope work ends
Review APISIX release notes with your team before each upgrade that touches authentication plugins
Agree the support boundaries, response expectations and escalation path in the written scope