Sign in

v50

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-07-068428533.0 MB
Realms

Create a realm

Create a new Realm. Centrally Managed Consumers are created within a Realm.

Each Realm can be restricted to a specific set of control planes if needed using allowed_control_planes or allow_all_control_planes.

ttl and negative_ttl control how long the consumers are kept in memory by a running Gateway.

Any consumer_groups added to the Realm are automatically applied to all consumers within this Realm.

post/v1/realms

Request body

namestring required
allowed_control_planesstring[]

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.

ttlinteger

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

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.

consumer_groupsstring[]

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.

Response

success

idstring required
namestring required
ttlinteger required

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

negative_ttlinteger required

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.

consumer_groupsstring[] required

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_planesstring[] required

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 required

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

created_atstring date-time required

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time required

An ISO-8601 timestamp representation of entity update date.

Example response

{
  "created_at": "2022-11-04T20:10:06.927Z",
  "updated_at": "2022-11-04T20:10:06.927Z"
}