Realms

Update a realm

Changed on

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/v1/realms/{realmId}

Request

  • Base URL: https://global.api.konghq.com
  • URL: https://global.api.konghq.com/v1/realms/{realmId}
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

Request body

namestring nullable
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.

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.

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.

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"
}

Changes

  • f530bf400198Revision changes
    • warning

      added the new 400.00 enum value to the response property for the response status

  • 4a02153f2e60Revision changes
    • breaking

      the response's body type changed from no type to object for status

    • info

      removed subschema #2 from the response body allOf list for the response status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status