How to design Apache APISIX consumers and credentials for your API clients
Before any route goes live in Apache APISIX, you need to know who calls each API and with which credential. In APISIX a *consumer* is the identity of an API caller, identified by a username. Authentication plugins such as key-auth, jwt-auth, hmac-auth and ldap-auth verify the caller's credential and attach the matching consumer to the request, so every later decision (rate limits, access rules, logging) can refer to that identity. A consumer per application is the usual starting point, and a separate consumer per partner is common when partners need their own credentials, limits and revocation. Teams that skip this modeling tend to share one API key across several services, which makes it impossible to tell callers apart in logs or to cut off one client without affecting the rest.
The design question is how many consumers you need and how their credentials map to them. Decide whether one consumer may hold several credentials, for example to rotate a key without downtime, and whether two systems ever share an identity. Also decide which consumers need a shared limit, since consumer groups let several consumers share plugin configuration. APISIX 3.18.0 rejects duplicate consumer authentication keys instead of silently accepting them, so confirm how your key naming and any import scripts behave against that rule before migrating existing clients. Plan the lifecycle as well: who creates a consumer, how credentials are issued and revoked, and whether the Admin API calls that do this are driven from version-controlled definitions rather than by hand.
Apache APISIX is released under the Apache License 2.0, and the 3.19.0 release is the current reference version for this guidance. Confirm the version you will run against the APISIX downloads page before you write automation, because consumer and credential schemas change between releases. DeployOpen plans and implements this consumer model, the credential lifecycle and the automation in your own infrastructure, with the consumer inventory, owners and revocation procedure agreed in writing before build work begins.
Consumer and credential options and when each fits
This table compares the main ways to model API callers in APISIX: one consumer with several credentials, one consumer per partner, consumer groups, and labels. Read each row for the situation it suits and the cost it carries, then match your partner and application structure to a model before writing any consumer objects.
| Option | When it fits | Trade-off to weigh |
|---|---|---|
| One consumer per application | Internal services or apps that share one owner and one set of limits | Rotating one app's key means touching its single consumer, and every credential on it shares its identity in logs |
| One consumer per partner, one credential per plugin | Partners who call through one authentication method, such as a single HMAC key or API key | Adding a second method for the same partner needs a design decision, since each plugin identifies the consumer by its own credential field |
| One consumer with several credentials | A partner or app that must rotate keys without downtime, or that needs overlapping old and new keys | Each credential must still be unique across consumers, and audit trails must map every credential back to one identity |
| Separate consumers for test and production | Partners integrating in a sandbox before going live, so test traffic never shares a limit or key with production | Doubles the consumer count and requires a naming rule so that test and production identities are never confused |
| Consumer groups for shared limits | Many consumers that must share one rate or quota policy, such as a partner tier | Groups share plugin configuration, so a change to the group affects every member; confirm the precedence behavior with your version |
| Labels for grouping and access rules | Reporting, restriction rules or automation that select consumers by business attribute, such as region or contract type | Labels carry no enforcement on their own; they work only where a plugin or your own tooling reads them |
| Anonymous consumer with lower limits | Public or unauthenticated traffic that should be allowed but throttled more tightly than named clients | Needs a separate policy and monitoring so anonymous traffic does not hide abuse inside normal numbers |
| Single consumer for all callers | Only a prototype or a single trusted caller | Makes every caller indistinguishable in logs and blocks per-partner revocation, so it is rarely suitable for regulated data |
How plugin precedence changes behavior across consumers and routes
APISIX resolves a plugin's effective configuration from several places at once, so the same plugin can be set on a consumer, a route, a plugin config and a service. The cards below cover the documented order and the specific ways that order can surprise a team when limits, authentication and headers are configured at more than one level.
Documented order of resolution
APISIX applies Consumer, then Route, then Plugin Config, then Service when the same plugin appears at more than one level. Write this order down for your team and confirm it against the consumer documentation for the APISIX version you run. Treat the order as the starting assumption for every test in this section, not as something a reader can infer from the file layout.
Route limit overriding a consumer limit
A rate limit on a route can take effect in place of the limit you intended for a consumer group, so a partner expecting a higher quota gets throttled at the route level. Illustrative case: a partner consumer is given a generous limit, but a route-level limit set years earlier for general traffic still applies to every caller. Test each consumer against each route it can reach and record the effective limit.
Plugin config shadowing service settings
Plugin Config objects are shared across many routes, so a change to one shared config can alter behavior on routes that never named it. Services sit lower in the order, which means a plugin set on a service may look active in the dashboard yet be ignored for any route that already defines that plugin. Export the resolved configuration for sample routes and compare it with what the team believes is deployed.
Authentication plugins set at two levels
If key-auth is enabled on a route and also on a plugin config, a request can be authenticated against a different rule than the one reviewed for that consumer. Decide in advance which level owns each authentication plugin, and forbid duplicate ownership in your review checklist. Verify with a request from each consumer type that the expected consumer is identified in logs.
Denials that depend on precedence
A consumer can be allowed on one route and denied on another because a restriction plugin attached at a higher or lower level wins for that path. Test denials as carefully as approvals, using one negative request per consumer and route pair before rollout. Include the anonymous or unauthenticated path, since a missing consumer can change which rule evaluates first.
Regression tests after any change
Precedence problems usually appear after an unrelated edit, such as adding a route or moving a plugin into a shared config. Build a small test set that covers each consumer, a sample of routes and the expected limit and status code for each combination, then run it in staging on every configuration change. Keep the results with the change record so an auditor can see what was tested.
Why APISIX 3.18 rejects duplicate consumer keys
APISIX 3.18.0 rejects duplicate consumer authentication keys instead of accepting them silently. Before this change, two consumers could end up sharing the same key without any error at write time, and the gateway would then have no reliable way to tell which application a request belonged to. Since the stricter check arrived in 3.18.0, a write that would create a duplicate is refused. For a design that issues keys per application or partner, this is the behavior you want, but it also means that data written under an older release may not meet the new rule. Treat the upgrade as a data review, not only a version bump.
The earlier change in 3.13.0 is related. It set additionalProperties to false for consumer credentials, so credential objects that carry unexpected fields are now rejected rather than stored. Migrations from another gateway or from an internal key store are where both rules tend to surface. Scripts that copy keys from several sources, such as a partner portal, a spreadsheet and a secrets manager, can produce the same key under two consumers or add fields the schema does not define. Teams that generated keys from multiple sources should expect failed imports and plan a deduplication pass that assigns each key to exactly one consumer before the import runs.
Before upgrading, confirm the exact APISIX version in every environment, including the data plane nodes and any standalone configuration files, and export the current consumer and credential objects through the Admin API for review. Check the APISIX changelog for the release notes that apply to your path, and run the export against a staging copy first. Record which keys are shared, which consumers were created by automation, and who owns each key, so that a rejected write during rollout can be traced to a specific source and fixed without disabling the check.
Setting up consumers and credentials through the Admin API
This sequence takes an APISIX gateway from a confirmed deployment to consumers, credentials and bound authentication plugins that you can test, reject and repeat from configuration you keep under version control.
Confirm deployment mode and Admin API access
Your platform engineer confirms which APISIX deployment mode is running. In traditional mode, the Admin API listens on port 9180 and client traffic arrives on port 9080, so the first check is that the team can reach port 9180 from a management network and that the Admin API key is stored in your secrets system, not in a shared file. In decoupled or standalone mode, confirm where configuration is written and who can change it before you create any objects. The step is done when a read request to the Admin API returns the current route list from the environment you intend to change.
Create consumer groups for shared limits
Before creating individual consumers, define consumer groups for clients that should share rate limits or plugin settings, such as a partner tier or an internal service class. The Admin API manages these groups as their own objects. Keep the group names aligned with the access model your security team has approved, because consumers will reference them. The step is done when a list request returns each group with the expected identifier and no unexpected entries.
Create one consumer per application or partner
Create a consumer for each application, service or partner that calls the gateway, using a username that identifies the caller in logs and audit records. Do not share one consumer across unrelated clients, because revoking one caller would then affect the others and the logs could not separate them. Assign each consumer to its consumer group where one applies. The step is done when each consumer returns from the Admin API with the expected username and group, and the list matches the register your team keeps for API clients.
Attach credentials under each consumer
For each consumer, add credentials at the nested path /apisix/admin/consumers/{username}/credentials, choosing the credential type that matches the authentication plugin planned for the routes, such as key-auth, jwt-auth or hmac-auth. Generate key material outside the request body where your policy requires it, and record which credential belongs to which environment. The step is done when a read of the credentials path returns each credential with its own identifier, and no two consumers share the same key value.
Bind authentication plugins to routes
Enable the chosen authentication plugin on the routes that should require it, and confirm that the plugin identifies the consumer from the credential. Apply plugin precedence deliberately: a plugin set on a consumer takes priority over the same plugin on a route, then on a plugin config, then on a service. The step is done when a route read shows the plugin enabled with the expected settings and when no route that should be protected is left without a plugin.
Verify with test requests and a rejected duplicate key
Send test requests with a valid credential, an invalid credential and no credential to each protected route, and confirm the gateway allows, rejects and denies them as expected. Then attempt to create a second consumer credential that reuses an existing key. Current APISIX releases reject duplicate consumer authentication keys instead of accepting them silently, so the request should fail. Confirm the version in your environment before you rely on that behavior. The step is done when every test result matches the expected outcome and the duplicate attempt is refused.
Keep consumer configuration as code
Store the consumer, group, credential and plugin definitions in a version-controlled repository and apply them through the same Admin API calls used in the steps above, so each change is reviewed and can be reproduced in another environment. Keep secret values out of the repository and load them from your secrets system at apply time. Ask your implementation partner or internal team to document who approves changes and how a revoked credential is removed. The step is done when a fresh environment built only from the repository passes the same test requests.
Automating consumer lifecycle with the Admin API
Can I manage APISIX consumers and credentials entirely through the Admin API?
Yes. The Admin API creates, updates and deletes consumers, consumer groups and the credentials nested under each consumer at /apisix/admin/consumers/{username}/credentials, so every change that a person could make in the dashboard or a configuration file can also be scripted. In practice this means onboarding, rotation and offboarding can run from a pipeline rather than from hand-edited YAML. Confirm the exact request bodies and fields for your APISIX version in the Admin API reference, because the schema tightened in recent releases, including additionalProperties set to false for consumer credentials in 3.13.0. Test each automated call against a non-production gateway first.
How do I rotate an API key without breaking a partner integration?
Rotate by overlap, not by replacement. Create a second credential for the same consumer, give the partner time to switch, confirm from gateway logs that the old credential has stopped carrying traffic, and then delete it. Because credentials sit under the consumer, both keys can belong to one partner record, which keeps ownership clear during the switch. Your automation should record the new credential's creation time and the planned deletion date so that the overlap window is visible to the people who approve it. The length of the window is a business decision agreed with the partner, not a platform setting.
What is the safest way to offboard a partner from APISIX?
Disable first, then remove after the retention period. Start by revoking or disabling the partner's credentials so that no new requests succeed, while keeping the consumer record so logs still resolve to a named owner. Then remove the consumer's routes access through consumer restrictions or groups if they are shared. Only delete the consumer and its credentials once your audit and retention rules allow it. Confirm with the partner which route and time window their traffic used, and keep the change ticket linked to the Admin API calls that performed each step.
How should onboarding forms or tickets trigger consumer creation?
A ticket or form should be the request, and the automation should be the only path that writes to APISIX. A typical flow has four parts:
- The requester submits the application name, owner, consumer group and required authentication type.
- An approver confirms the scope, including which routes the consumer may call.
- A pipeline calls the Admin API to create the consumer, its credentials and any group membership, and stores the generated key in a secrets manager rather than in the ticket.
- The pipeline writes the outcome back to the ticket with the consumer name and creation time.
Keep the approval step outside APISIX so that the gateway configuration always reflects an approved request.
How do I reconcile APISIX consumers with our identity or CMDB source of truth?
Treat the external system as the source of truth and run a scheduled reconciliation job that compares it with the consumers returned by the Admin API. The job should list consumers present in APISIX but absent from the source, consumers in the source but missing from APISIX, and credentials older than your rotation policy. Report differences first and apply corrections only after review, because an accidental delete removes live access. Store consumer names that match your directory or inventory identifiers so that the comparison is a simple key match. Ask your team how often the source changes, since that sets how often reconciliation needs to run.
What audit trail should we keep for consumer and credential changes?
Keep three records for every change: who approved it, which automation or operator made the Admin API call, and what changed in APISIX. The approval lives in the ticket system, the call identity lives in the pipeline or service account logs, and the configuration state can be captured by exporting the consumer object before and after each change. Store the owner of each consumer as a field or label so that an auditor can trace a key to an accountable team without reading code. Do not store credential values in these records. Confirm with your compliance lead which retention period and access controls apply to these records.
Who should own the automation that manages APISIX consumers?
Ownership usually sits with the platform or API team that operates the gateway, with the application or partner teams owning the business request. The platform team owns the pipeline, the service account, the schema versions and the reconciliation job, because a change to the Admin API can affect every consumer. Application teams own the accuracy of their consumer record, the list of routes they need and the timing of their own rotations. Write this split into the runbook so that a missing owner is noticed before a credential expires. A partner or implementation team can build and hand over this automation, but your staff should be able to operate it afterward.
Can we build this lifecycle automation ourselves, and what would a partner add?
A team with API and pipeline experience can build consumer automation in-house, since the work is a set of authenticated Admin API calls, approval hooks and a reconciliation job. The effort depends on how many authentication types you run, how many systems feed onboarding, and how strict your audit requirements are. A partner typically adds design review of the consumer model, tested rotation and offboarding runbooks, and documentation for your operators. DeployOpen plans and implements this work as a fixed-scope engagement, with scope, deliverables and timelines agreed in writing before work starts, and the quote follows from that written scope.
Securing stored credentials and the Admin API that manages them
Consumers and their credentials are only as trustworthy as the process that writes them. The cards below cover who can change consumer records, how credential secrets are kept out of configuration files and logs, and what evidence you need to show who changed what. Gateway-level hardening of the Admin API, etcd and TLS is covered on a separate page and is referenced here rather than repeated.
Protecting Admin API keys
The Admin API on port 9180 in traditional mode accepts changes to consumers and credentials, so its access key is effectively a administrative credential for every API client you run. Replace the default admin key before any environment is reachable, store it in your secrets manager, and give automation its own scoped key rather than sharing the administrator key. Confirm which keys can create consumers and which can only read them.
Restricting who can change consumers
Decide which people and pipelines may create, modify or delete consumers and credentials, and keep that list short. Route consumer changes through version-controlled pipelines with review, so a single operator cannot issue a new key for a partner in production. Check that network access to the Admin API is limited to management hosts and CI runners, and that read-only access is granted separately from write access.
Keeping secrets out of config and logs
Credential values appear in Admin API payloads, declarative configuration files and request or debug logs if you are not careful. Store consumer secrets through a secret reference where your APISIX version supports it, keep exported configuration files out of general repositories, and review gateway log settings so that headers carrying keys are not written in clear text. Test this by searching your log pipeline for a known test key after a deliberate call.
Auditing consumer and credential changes
Operations teams need a record of who created, rotated or disabled a credential and when. The Admin API does not replace an audit trail on its own, so confirm whether your deployment captures change history through the pipeline that calls it, your etcd backups or your ticketing system. Define retention for those records in advance and test that you can answer the question for a specific partner key within minutes.
Separating gateway hardening from credential control
Securing the Admin API transport, etcd access, TLS and the control plane is a separate piece of work from modeling consumers and their keys. Treat the gateway hardening scope as a prerequisite for the controls on this page, and agree who owns each item before the build starts. Gaps in either area will undermine the other, so review them together at sign-off.
What designing APISIX consumers and credentials costs and requires
What drives the effort of designing APISIX consumers and credentials?
The main drivers are the number of API clients, the number of authentication and authorization plugins in use, whether you are moving clients from another gateway, how many identity sources must be connected, and how much testing is needed before rollout. Each consumer needs a clear owner, a credential type that fits its traffic, and a set of allowed routes. A few dozen clients on one plugin is a far smaller job than hundreds of partner clients using key-auth, hmac-auth and mTLS together, where credential formats, rotation rules and denial tests multiply. Ask any partner to show how each of these items is counted in the written scope before agreeing on effort.
How long does consumer and credential design take?
Duration depends on the scope agreed in writing, not on a general rule. A scope limited to a documented consumer model for one application and one credential type is short, while a scope covering many partners, several plugins, a gateway migration and automated onboarding is much longer. No duration is published here, so ask any provider to break the timeline into inventory, design, build, testing and handover, and to state which items are included and which are excluded. Your own environment, change windows and approval cycles will also affect the calendar.
What must our team provide before consumer design starts?
Prepare a client inventory listing every application, partner and machine caller, with a named business owner and technical contact for each. Add the identity sources they use, such as an LDAP directory, an OpenID Connect provider or a certificate authority, and the environments where they call the gateway, including development, test and production. You should also document which routes each client needs, current credential types, rotation expectations and any service level commitments you already give partners. Access to a non-production APISIX instance and to the Admin API for review is usually needed early, and your security team should confirm where credentials may be stored.
Can an internal platform team design APISIX consumers on its own?
A capable internal team can do it, especially if it already runs APISIX or another gateway and has clear ownership of API clients. The hard parts are less about syntax and more about consistent naming, plugin precedence, credential isolation and testing denials before rollout. Teams often underestimate the time needed to get business owners to agree on who owns each consumer and which routes they may call. Decide what you will build internally, what you will buy as a fixed-scope engagement, and who will own the design after handover. Check your own skills against the plugin list in the scope before you commit.
What recurs after go-live for consumers and credentials?
Several tasks recur. Credentials need rotation on a schedule your security policy sets, and key-auth or hmac-auth secrets may need to change without downtime. New partners and applications must be onboarded through a repeatable process that creates the consumer, its credentials and its consumer group, then tests denials. Offboarding must disable or delete consumers and their credentials quickly. Plugin upgrades can change credential schema rules, so review the APISIX changelog before each upgrade. Decide whether these tasks stay with your team, move into an automation pipeline using the Admin API, or are covered by an ongoing support arrangement.
What security and compliance evidence should we ask for?
Ask for a written record of how each consumer and credential is owned, approved, rotated and removed, along with the test results that show denied calls behave as designed. Duplicate and malformed credentials should be tested, and the design should state where secrets are stored and who can read them. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations, so confirm with your assessor which evidence they expect from your access control records.
How should we ask for a quote for consumer design work?
Request a fixed-scope proposal that lists the consumer inventory size, the plugins in scope, whether a gateway migration is included, the identity integrations, the test cases and the handover materials. DeployOpen does not publish a price list, and a quote follows from the written scope. Ask which items are one-time and which are retainers, what the provider needs from you, and what changes would alter the price or timeline. Compare proposals on the same inventory and acceptance criteria, not on headline totals.
How DeployOpen scopes, builds and supports this work
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including the APISIX gateway and the consumer model described on this page. The work runs in your cloud accounts, data centers or restricted networks, so the consumer records, credential stores, Admin API access and audit logs stay under your control. Scope starts with an inventory of the API clients you need to model: which applications, partners and machine callers exist, which of them need a separate consumer, which ones should share a consumer group for limits, and which credential types each one uses. That inventory becomes the basis of the written scope.
Most engagements are fixed-scope. Before work starts, the scope, deliverables and timelines are agreed in writing, and that document names the consumers, the credential types, the Admin API automation to be built and the tests to be run before cutover. A quote follows from that written scope, so the figures you receive reflect the items listed rather than a generic package. Ask for the quote to separate the one-time build (consumer model, credential issuance and rotation automation, duplicate-key checks, documentation) from any recurring items, and to state which environments, approval steps and customer-side tasks it assumes. Confirm with your team which APISIX version you will run before scope is fixed, since release behavior differs across versions.
After handover, ongoing support, version upgrades and continuous testing are available as a retainer. For consumers and credentials, the recurring work is usually onboarding new partners, rotating keys, reviewing consumer groups and checking that the lifecycle automation still matches the Admin API of the running version. DeployOpen does not issue audit reports, attestations or certifications. Where you need evidence for an assessment, the work produces the configuration, logs and records that your auditor or certification body will examine, and you should confirm with them in advance which evidence they expect.
