Consumers API

Overview

A consumer is the credential-based identity that calls your API proxies. This API is the write surface for consumers. It replaces the Credentials API, which is deprecated and addresses the same records by username.

Every address is under /apiops/projects/{projectName} and follows the shared Common Contract: the stable error envelope, correlation IDs and bounded pagination.

How the API behaves

• Addressed by consumer key. The installation assigns the consumerKey when you create the consumer. A create request that names a consumerKey is refused with 400 immutableField. Use the consumerKey from the create response in every later path.
• Create answers 201 and a Location header with the address of the new consumer.
• Update is a JSON Merge Patch. A field that the body omits (or sends as null) keeps its stored value. Send an empty list or an empty string to clear a field. Send "expireDate": null to remove the expiry.
• Some fields cannot change on an update. username and consumerKey are immutable (400 immutableField). The password changes only with Change Consumer Password. The organization changes only with the transfer action.
• Identity-source consumers are read-only here. A consumer that a live identity source manages (LDAP, OIDC, database or API sync) cannot be edited. The write answers 400 malformedRequest with params.reason = ldapManaged. The same rule applies on the Manager screen. Enable and Disable are the exception: they are accepted on such a consumer.
• Secret values are write-only. No response returns a password or the value of a secret metadata entry.
• Writes report the gateway push. Every write stores the change, pushes it to the environments and answers with runtimeDeployment: IN_SYNC or DEGRADED. A DEGRADED write is stored. See Write responses.

Endpoints

CRUD Operations

Method	Path	Description
GET	/consumers	List Consumers
GET	/consumers/{consumerKey}	Get Consumer
POST	/consumers	Create Consumer
PUT	/consumers/{consumerKey}	Update Consumer
POST	/consumers/{consumerKey}/actions/change-password	Change Consumer Password
POST	/consumers/{consumerKey}/actions/enable	Enable Consumer
POST	/consumers/{consumerKey}/actions/disable	Disable Consumer
POST	/consumers/{consumerKey}/actions/sync-match	Match Consumer to an Identity Source User
DELETE	/consumers/{consumerKey}	Delete Consumer
POST	/consumers/{consumerKey}/actions/transfer-organization	Transfer to another organization

Access

Method	Path	Description
GET	/consumers/{consumerKey}/access	List Consumer Access
POST	/consumers/{consumerKey}/access	Grant Consumer Access
PUT	/consumers/{consumerKey}/access/api-proxies/{apiProxyName}	Update Consumer Access to an API Proxy
PUT	/consumers/{consumerKey}/access/proxy-groups/{proxyGroupName}	Update Consumer Access to an API Proxy Group
POST	/consumers/{consumerKey}/access/actions/revoke	Revoke Consumer Access

Secret material, JWK and token settings

Two read operations return the current state: Get Consumer Token Settings (GET /consumers/{consumerKey}/token-settings) and Get Consumer Secret References (GET /consumers/{consumerKey}/secrets). The second returns the name and scope of each reference, never the material.

Each reference below has a set operation (PUT, name in the path) and a remove operation (DELETE).

Reference	Set	Remove
Secret key	Set	Remove
Certificate	Set	Remove
Public key	Set	Remove
Private key	Set	Remove
Keystore	Set	Remove
Truststore	Set	Remove
JWK for validation and signing	Set	Remove
JWK for decryption and encryption	Set	Remove
Token settings	Set	Reset

Read-only sub-resources

The API clients and the limit assignments of a consumer are read on the Consumers & Applications API:

• GET /consumers/{consumerKey}/api-clients
• GET /consumers/{consumerKey}/limit-assignments

Consumer roles

Roles live on a separate collection, /consumer-roles. See the Consumer Roles API.

Consumer organizations

Organizations live on a separate collection, /consumer-organizations. See the Consumer Organizations API.

Permissions

Operation	Required Permission
List, Get, List Access, Get Token Settings, Get Secret References	IDENTITY + VIEW
Create, Update, Change Password, Enable, Disable, Match to an Identity Source User, Delete, Grant, Update and Revoke Access, secret material, JWK, token settings	IDENTITY + MANAGE

Related Documentation

• Consumers & Applications API - Read endpoints, API clients, limit assignments and the organization transfer action
• Consumer Roles API - Roles that you give to consumers
• Consumer Organizations API - Organizations of consumers
• Credentials API (deprecated) - The earlier surface, addressed by username
• Common Contract - Errors, pagination and write responses