Get a realm

Fetch the details of a specific realm, identified by its UUID

get

Path Parameters

realmIdstring(uuid)required

ID of the realm

Response

200 application/json

success

ConsumerRealm

idstringrequired
namestringrequired
ttlintegerrequired

The time in minutes that the Consumer will be cached in memory on a running Gateway if it is
successfully loaded from Konnect.

Default:10

>= 5

negative_ttlintegerrequired

If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a negative_ttl
is set. The Gateway will not try to lookup the Consumer in Konnect for negative_ttl minutes.

A Consumer will be cached for negative_ttl if they do not exist in the Realm, or if the provided credentials
are invalid.

Default:10

>= 5

consumer_groupsarray[string](set)requiredunique-items

A list of consumer groups to automatically add to any consumers created within this Realm.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

allowed_control_planesarray[string](set)requiredunique-items

List of control plane ids that are allowed to use the realm. This is used when allow_all_control_planes value
is set to false.

allow_all_control_planesbooleanrequired

Allow all control planes to use the realm. When this value is set it takes precedence on allowed_control_planes.

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}
 
200 application/json

Update a realm

Update a realm’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

Body

application/json

ConsumerRealmUpdateRequest

* Additional properties are NOT allowed.
namestring
allowed_control_planesarray[string](set)unique-items

List of control plane ids that are allowed to use the realm. This is used when allow_all_control_planes value
is set to false.

allow_all_control_planesboolean

Allow all control planes to use the realm. When this value is set it takes precedence on allowed_control_planes.

consumer_groupsarray[string](set)unique-items

A list of consumer groups to automatically add to any consumers created within this Realm.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

ttlinteger

The time in minutes that the Consumer will be cached in memory on a running Gateway if it is
successfully loaded from Konnect.

Default:10

>= 5

negative_ttlinteger

If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a negative_ttl
is set. The Gateway will not try to lookup the Consumer in Konnect for negative_ttl minutes.

A Consumer will be cached for negative_ttl if they do not exist in the Realm, or if the provided credentials
are invalid.

Default:10

>= 5

Response

application/json

success

ConsumerRealm

idstringrequired
namestringrequired
ttlintegerrequired

The time in minutes that the Consumer will be cached in memory on a running Gateway if it is
successfully loaded from Konnect.

Default:10

>= 5

negative_ttlintegerrequired

If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a negative_ttl
is set. The Gateway will not try to lookup the Consumer in Konnect for negative_ttl minutes.

A Consumer will be cached for negative_ttl if they do not exist in the Realm, or if the provided credentials
are invalid.

Default:10

>= 5

consumer_groupsarray[string](set)requiredunique-items

A list of consumer groups to automatically add to any consumers created within this Realm.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

allowed_control_planesarray[string](set)requiredunique-items

List of control plane ids that are allowed to use the realm. This is used when allow_all_control_planes value
is set to false.

allow_all_control_planesbooleanrequired

Allow all control planes to use the realm. When this value is set it takes precedence on allowed_control_planes.

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}

Body

{ "name": "MyKingdom" }
 
application/json

Delete a realm

Delete a Realm, and all consumers and credentials containined within the Realm.

Only empty Realms can be deleted, unless you specify ?force=true as a query string parameter in your request.

delete

Query Parameters

forcestring

If true, delete specified realm and all underlying entities (consumers/apiKeys). If false, do not allow deletion if there are underlying entities.

Allowed values:truefalse

Default:false

Path Parameters

realmIdstring(uuid)required

ID of the realm

Response

success

delete/realms/{realmId}
 

Centrally Managed Consumers

Consumers can be scoped to a Konnect region and managed centrally, or be scoped to a control plane in Gateway Manager. Use centrally managed consumers to set up identity of the consumer once, and share it across multiple control planes. Consumers that are managed centrally aren’t part of the configuration that is pushed down from the control plane to the data planes, so it reduces config size and latency.

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