List realm consumers

List all realm-scoped consumers. This operation allows you to look for consumers across multiple realms.

get

Query Parameters

page[size]integer

The maximum number of items to include per page. The last page of a collection may include fewer items.

Example:10

page[before]string

Request the next page of data, starting with the item before this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

page[after]string

Request the next page of data, starting with the item after this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

filterobject

Filters Consumers in the response.

Show Child Parameters

Response

200 application/json

success

ListRealmConsumers

dataarray[object]required

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

Example:{"custom_id":"4200","id":"8a388226-80e8-4027-a486-25e4f7db5d21","type":"proxy","consumer_groups":["gold"],"tags":["partner"],"username":"bob-the-builder","created_at":"2025-06-17T16:55:58.569399532Z","updated_at":"2025-06-17T16:55:58.569399532Z","realm_id":"77fd4d02-5d87-4f76-90a9-1bd6ce152c36"}

* Additional properties are NOT allowed.
Show Child Parameters
metaobjectrequired

Pagination metadata.

Show Child Parameters
get/realm-consumers
 
200 application/json

List consumers

List all consumers that are a member of this realm.

get

Query Parameters

page[size]integer

The maximum number of items to include per page. The last page of a collection may include fewer items.

Example:10

page[before]string

Request the next page of data, starting with the item before this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

page[after]string

Request the next page of data, starting with the item after this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

filterobject

Filters Consumers in the response.

Show Child Parameters

Path Parameters

realmIdstring(uuid)required

ID of the realm

Response

application/json

success

ListConsumers

dataarray[object]required

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

Example:{"custom_id":"4200","id":"8a388226-80e8-4027-a486-25e4f7db5d21","type":"proxy","consumer_groups":["gold"],"tags":["partner"],"username":"bob-the-builder","created_at":"2025-06-17T16:55:58.569399532Z","updated_at":"2025-06-17T16:55:58.569399532Z"}

* Additional properties are NOT allowed.
Show Child Parameters
metaobjectrequired

Pagination metadata.

Show Child Parameters
get/realms/{realmId}/consumers
 
application/json

Create a consumer

Create a new consumer in this Realm. It will be available to use for authentication within a few seconds, unless
the consumer’s username is blocked in the Gateway. If this is the case, the new consumer will be available in
negative_ttl (see the Realm definition) seconds.

post

Path Parameters

realmIdstring(uuid)required

ID of the realm

Body

application/json

ConsumerCreateRequest

* Additional properties are NOT allowed.
usernamestringrequired

The unique username of the Consumer.

>= 1 characters

custom_idstring

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database.

>= 1 characters

consumer_groupsarray[string]unique-items

A list of consumer groups that the Consumer is in.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

typestring

Type of the consumer.

Allowed values:proxydeveloperadminapplication

Default:proxy

tagsarray[string]unique-items

Response

application/json

success

CentralizedConsumer

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

* Additional properties are NOT allowed.
idstring(uuid)requiredread-only

The Consumer ID.

Example:b9e81174-b5bb-4638-a3c3-8afe61a0abf8

usernamestring | nullrequired

The unique username of the Consumer. You must send either this field or custom_id with the request.

custom_idstring | nullrequired

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

typestringrequired

Type of the consumer.

Allowed values:proxydeveloperadminapplication

Default:proxy

tagsarray[string]requiredunique-items
consumer_groupsarray[string]requiredunique-items

A list of consumer groups that the Consumer is in.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

created_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity creation date.

Example:2022-11-04T20:10:06.927Z

updated_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity update date.

Example:2022-11-04T20:10:06.927Z

post/realms/{realmId}/consumers

Body

{ "username": "J4son" }
 
application/json

Get a consumer

Get a consumer from the given realm.

get

Path Parameters

realmIdstring(uuid)required

ID of the realm

consumerIdstringrequired

ID of the of the consumer

Response

application/json

success

CentralizedConsumer

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

* Additional properties are NOT allowed.
idstring(uuid)requiredread-only

The Consumer ID.

Example:b9e81174-b5bb-4638-a3c3-8afe61a0abf8

usernamestring | nullrequired

The unique username of the Consumer. You must send either this field or custom_id with the request.

custom_idstring | nullrequired

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

typestringrequired

Type of the consumer.

Allowed values:proxydeveloperadminapplication

Default:proxy

tagsarray[string]requiredunique-items
consumer_groupsarray[string]requiredunique-items

A list of consumer groups that the Consumer is in.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

created_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity creation date.

Example:2022-11-04T20:10:06.927Z

updated_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity update date.

Example:2022-11-04T20:10:06.927Z

get/realms/{realmId}/consumers/{consumerId}
 
application/json

Update a consumer

Update a Consumer’s details. Any consumers already cached in a running Gateway will not be affected body the changes to the Realm until ttl minutes have passed.

patch

Path Parameters

realmIdstring(uuid)required

ID of the realm

consumerIdstringrequired

ID of the of the consumer

Body

application/json

UpdateConsumerPayload

* Additional properties are NOT allowed.
usernamestring

The unique username of the Consumer.

>= 1 characters

custom_idstring | null

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database.

>= 1 characters

consumer_groupsarray | null[string]unique-items

A list of consumer groups that the Consumer is in.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

typestring

Type of the consumer.

Allowed values:proxydeveloperadminapplication

Default:proxy

tagsarray[string]unique-items

Response

application/json

success

CentralizedConsumer

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

* Additional properties are NOT allowed.
idstring(uuid)requiredread-only

The Consumer ID.

Example:b9e81174-b5bb-4638-a3c3-8afe61a0abf8

usernamestring | nullrequired

The unique username of the Consumer. You must send either this field or custom_id with the request.

custom_idstring | nullrequired

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

typestringrequired

Type of the consumer.

Allowed values:proxydeveloperadminapplication

Default:proxy

tagsarray[string]requiredunique-items
consumer_groupsarray[string]requiredunique-items

A list of consumer groups that the Consumer is in.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

created_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity creation date.

Example:2022-11-04T20:10:06.927Z

updated_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity update date.

Example:2022-11-04T20:10:06.927Z

patch/realms/{realmId}/consumers/{consumerId}

Body

{ "username": "Jason" }
 
application/json