---
title: "Konnect Centrally Managed Consumers admin api"
url: "https://nov18-dev.movespot.fyi/apis/konnect-centrally-managed-consumers-admin-api-0/versions/84f5e371-6d0e-45b1-b943-fe4dc428c317"
---

# Konnect Centrally Managed Consumers admin api

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Konnect Centrally Managed Consumers admin api","version":"0.0.1"},"servers":[{"url":"https://us.api.konghq.com/v1","description":"United-States Production region"},{"url":"https://eu.api.konghq.com/v1","description":"Europe Production region"},{"url":"https://au.api.konghq.com/v1","description":"Australia Production region"},{"url":"https://me.api.konghq.com/v1","description":"Middle-East Production region"},{"url":"https://in.api.konghq.com/v1","description":"India Production region"},{"url":"https://sg.api.konghq.com/v1","description":"Singapore Production region"}],"paths":{"/realm-consumers":{"get":{"operationId":"list-realms-consumers","summary":"List realm consumers","description":"List all realm-scoped consumers. This operation allows you to look for consumers across multiple realms.","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageBefore"},{"$ref":"#/components/parameters/PageAfter"},{"$ref":"#/components/parameters/RealmConsumerFilters"}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRealmConsumers"},"examples":{"ListRealmConsumers":{"$ref":"#/components/examples/ListRealmConsumers"}}}}}},"tags":["Centrally Managed Consumers"]}},"/realms":{"get":{"operationId":"list-realms","summary":"List realms","description":"List all available realms. The full configuration of each Realm is returned under the `data` key\n","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageBefore"},{"$ref":"#/components/parameters/PageAfter"}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRealms"},"examples":{"ListRealms":{"$ref":"#/components/examples/ListRealms"}}}}}},"tags":["Realms"]},"post":{"operationId":"create-realm","summary":"Create a realm","description":"Create a new Realm. Centrally Managed Consumers are created within a Realm. \n\nEach Realm can be restricted to a specific set of control planes if needed using `allowed_control_planes` or `allow_all_control_planes`.\n\n`ttl` and `negative_ttl` control how long the consumers are kept in memory by a running Gateway. \n\nAny `consumer_groups` added to the Realm are automatically applied to all consumers within this Realm.\n","requestBody":{"$ref":"#/components/requestBodies/CreateConsumerRealm"},"responses":{"201":{"$ref":"#/components/responses/CreateConsumerRealmResponse"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{"TTLTooLow":{"value":{"status":400,"title":"Bad Request","instance":"kong:trace:6816496025408232265","detail":"Bad Request","invalid_parameters":[{"field":"ttl","rule":"min","source":"body","reason":"must be higher than 5","minimum":5}]}}}}}}},"tags":["Realms"]}},"/realms/{realmId}":{"parameters":[{"$ref":"#/components/parameters/realmId"}],"get":{"operationId":"get-realm","summary":"Get a realm","description":"Fetch the details of a specific realm, identified by its UUID","responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerRealm"},"examples":{"Realm":{"$ref":"#/components/examples/Realm"}}}}}},"tags":["Realms"]},"patch":{"operationId":"update-realm","summary":"Update a realm","description":"Update a realm's details. Any consumers already cached in a running Gateway will not be affected body\nthe changes to the Realm until `ttl` minutes have passed.\n","requestBody":{"$ref":"#/components/requestBodies/UpdateConsumerRealm"},"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerRealm"},"examples":{"Realm":{"$ref":"#/components/examples/Realm"}}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{"TTLTooLow":{"value":{"status":400,"title":"Bad Request","instance":"kong:trace:6816496025408232265","detail":"Bad Request","invalid_parameters":[{"field":"ttl","rule":"min","source":"body","reason":"must be higher than 5","minimum":5}]}}}}}}},"tags":["Realms"]},"delete":{"operationId":"delete-realm","summary":"Delete a realm","description":"Delete a Realm, and all consumers and credentials containined within the Realm.\n\nOnly empty Realms can be deleted, unless you specify `?force=true` as a query string parameter in your request.\n","parameters":[{"name":"force","in":"query","description":"If true, delete specified realm and all underlying entities (consumers/apiKeys). If false, do not allow deletion if there are underlying entities.","schema":{"type":"string","default":"false","enum":["true","false"]}}],"responses":{"204":{"description":"success"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{"TTLTooLow":{"value":{"status":400,"title":"Bad Request","instance":"kong:trace:6816496025408232265","detail":"Bad Request","invalid_parameters":[{"field":"force","rule":"required","source":"query","reason":"cannot delete non-empty realm without ?force=true"}]}}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Realms"]}},"/realms/{realmId}/consumers":{"parameters":[{"$ref":"#/components/parameters/realmId"}],"get":{"operationId":"list-consumers-per-realm","summary":"List consumers","description":"List all consumers that are a member of this realm. \n","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageBefore"},{"$ref":"#/components/parameters/PageAfter"},{"$ref":"#/components/parameters/ConsumerFilters"}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListConsumers"},"examples":{"ListConsumers":{"$ref":"#/components/examples/ListConsumers"}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Consumers"]},"post":{"operationId":"create-consumer-in-realm","summary":"Create a consumer","description":"Create a new consumer in this Realm. It will be available to use for authentication within a few seconds, unless\nthe consumer's username is blocked in the Gateway. If this is the case, the new consumer will be available in\n`negative_ttl` (see the Realm definition) seconds.\n","requestBody":{"$ref":"#/components/requestBodies/CreateConsumer"},"responses":{"201":{"$ref":"#/components/responses/CreateConsumerResponse"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Consumers"]}},"/realms/{realmId}/consumers/{consumerId}":{"parameters":[{"$ref":"#/components/parameters/realmId"},{"$ref":"#/components/parameters/consumerId"}],"get":{"operationId":"get-consumer-from-realm","summary":"Get a consumer","description":"Get a consumer from the given realm.\n","responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralizedConsumer"},"examples":{"Consumer":{"$ref":"#/components/examples/Consumer"}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Consumers"]},"patch":{"operationId":"update-consumer-in-realm","summary":"Update a consumer","description":"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.\n","requestBody":{"$ref":"#/components/requestBodies/UpdateConsumer"},"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralizedConsumer"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Consumers"]},"delete":{"operationId":"delete-consumer-in-realm","summary":"Delete a consumer","description":"Delete a consumer. This operation removes the consumer from the system, causing all future authentication\nrequests using keys associated with that consumer to fail. However, it does not immediately invalidate any\ncached keys stored in the gateway's state. These keys may remain usable until the cache expires, based on the\nTTL (Time-To-Live) configured for the realm.\n","responses":{"204":{"description":"success"},"404":{"description":"not found"}},"tags":["Centrally Managed Consumers"]}},"/realms/{realmId}/consumers/{consumerId}/move":{"parameters":[{"$ref":"#/components/parameters/realmId"},{"$ref":"#/components/parameters/consumerId"}],"post":{"operationId":"move-consumer","summary":"Change the realm of a consumer","description":"Change the realm membership of a consumer without changing their credentials.\n","requestBody":{"$ref":"#/components/requestBodies/MoveConsumer"},"responses":{"201":{"$ref":"#/components/responses/MoveConsumerResponse"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Consumers"]}},"/realms/{realmId}/consumers/{consumerId}/keys":{"parameters":[{"$ref":"#/components/parameters/realmId"},{"$ref":"#/components/parameters/consumerId"}],"get":{"operationId":"list-consumer-keys","summary":"List keys","description":"List all the credential keys related to this consumer.\nThese keys are used by the kay-auth plugin to authenticate the consumer.\n","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageBefore"},{"$ref":"#/components/parameters/PageAfter"}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListKeys"},"examples":{"ListConsumerKeys":{"$ref":"#/components/examples/ListConsumerKeys"}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Keys"]},"post":{"operationId":"create-consumer-key","summary":"Create a key","description":"This operation generates an API key for the specified consumer. The key is returned only at the time of creation\nand will not be retrievable in any subsequent GET requests on the entity.\n\nThe API supports two key creation types: `new` and `legacy`.\n\n* `new`: The recommended and more efficient option. The API automatically generates the key and returns it during\nthis operation.\n* `legacy`: Allows you to provide your own secret. This approach has a performance impact when proxying requests, as it involves\nadditional processing and resource usage.\n\nNote: Regardless of the type selected, the key is only returned by the API when a key is created. It is not retrievable in the future.\n","requestBody":{"$ref":"#/components/requestBodies/CreateApiKey"},"responses":{"201":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResult"},"examples":{"CreateKeyResult":{"$ref":"#/components/examples/CreateApiKeyResult"},"CreateApiKeyResultLegacy":{"$ref":"#/components/examples/CreateApiKeyResultLegacy"}}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"},"examples":{"BadType":{"value":{"status":400,"title":"Bad Request","instance":"kong:trace:6816496025408232265","detail":"Bad Request","invalid_parameters":[{"field":"type","rule":"enum","source":"body","reason":"must be one of: [legacy,new]","choices":["legacy","new"]}]}}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Keys"]}},"/realms/{realmId}/consumers/{consumerId}/keys/{keyId}":{"parameters":[{"$ref":"#/components/parameters/realmId"},{"$ref":"#/components/parameters/consumerId"},{"$ref":"#/components/parameters/keyId"}],"get":{"operationId":"get-consumer-key","summary":"Get a key","description":"Returns the key entity. This operation does **NOT** return the key itself. The key is only available at the time of creation.\n","responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"},"examples":{"ApiKey":{"$ref":"#/components/examples/ApiKey"}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"tags":["Centrally Managed Keys"]},"delete":{"operationId":"delete-consumer-key","summary":"Delete a key","description":"Delete a key. This operation removes the key from the system, causing all future authentication\nrequests using this key to fail. However, it does not immediately invalidate any\ncached keys stored in the gateway's state. These keys may remain usable until the cache expires, based on the\nTTL (Time-To-Live) configured for the realm.\n","responses":{"204":{"description":"success"},"404":{"description":"not found"}},"tags":["Centrally Managed Keys"]}}},"components":{"parameters":{"ConsumerFilters":{"name":"filter","description":"Filters Consumers in the response.","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ConsumerFilterParameters"},"style":"deepObject"},"consumerId":{"name":"consumerId","in":"path","required":true,"description":"ID of the of the consumer","schema":{"type":"string"}},"keyId":{"name":"keyId","in":"path","required":true,"description":"ID of the key","schema":{"type":"string"}},"PageAfter":{"name":"page[after]","description":"Request the next page of data, starting with the item after this parameter.","required":false,"in":"query","allowEmptyValue":true,"schema":{"type":"string","example":"ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ"}},"PageBefore":{"name":"page[before]","description":"Request the next page of data, starting with the item before this parameter.","required":false,"in":"query","allowEmptyValue":true,"schema":{"type":"string","example":"ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ"}},"PageSize":{"name":"page[size]","description":"The maximum number of items to include per page. The last page of a collection may include fewer items.","required":false,"in":"query","allowEmptyValue":true,"schema":{"type":"integer","example":10}},"RealmConsumerFilters":{"name":"filter","description":"Filters Consumers in the response.","required":false,"in":"query","schema":{"$ref":"#/components/schemas/RealmConsumerFilterParameters"},"style":"deepObject"},"realmId":{"name":"realmId","in":"path","required":true,"description":"ID of the realm","schema":{"type":"string","format":"uuid"}}},"schemas":{"RealmConsumerFilterParameters":{"type":"object","properties":{"custom_id":{"description":"Filter using **one** of the following operators: `eq`","properties":{"eq":{"description":"The field exactly matches the provided value.","type":"string","example":"?filter[field_name_here][eq]=foo"}},"x-examples":{"example-1":"equals-some-value","example-2":{"eq":"some-value"}}},"username":{"description":"Filter using **one** of the following operators: `eq`","properties":{"eq":{"description":"The field exactly matches the provided value.","type":"string","example":"?filter[field_name_here][eq]=foo"}},"x-examples":{"example-1":"equals-some-value","example-2":{"eq":"some-value"}}}}},"ConsumerFilterParameters":{"type":"object","properties":{"custom_id":{"description":"Filter using **one** of the following operators: `eq`","properties":{"eq":{"description":"The field exactly matches the provided value.","type":"string","example":"?filter[field_name_here][eq]=foo"}},"x-examples":{"example-1":"equals-some-value","example-2":{"eq":"some-value"}}},"username":{"description":"Filter using **one** of the following operators: `eq`","properties":{"eq":{"description":"The field exactly matches the provided value.","type":"string","example":"?filter[field_name_here][eq]=foo"}},"x-examples":{"example-1":"equals-some-value","example-2":{"eq":"some-value"}}}}},"CreateApiKeyPayload":{"oneOf":[{"$ref":"#/components/schemas/CreateApiKeyPayloadNew"},{"$ref":"#/components/schemas/CreateApiKeyPayloadLegacy"}]},"CreateApiKeyPayloadNew":{"type":"object","properties":{"type":{"type":"string","default":"new","enum":["new"]},"tags":{"$ref":"#/components/schemas/Tags"}},"additionalProperties":false,"required":["type"]},"CreateApiKeyPayloadLegacy":{"type":"object","properties":{"type":{"type":"string","default":"legacy","enum":["legacy"]},"secret":{"description":"secret to be created. Must be unique within the realm. If not specified a secret will be automatically generated.","type":"string","x-sensitive":true},"tags":{"$ref":"#/components/schemas/Tags"}},"additionalProperties":false,"required":["type","secret"]},"CreateApiKeyResult":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/KeyTypeEnum"},"secret":{"type":"string","x-sensitive":true},"created_at":{"$ref":"#/components/schemas/CreatedAt"},"updated_at":{"$ref":"#/components/schemas/UpdatedAt"},"tags":{"$ref":"#/components/schemas/Tags"}},"required":["id","type","secret","created_at","updated_at","tags"]},"KeyTypeEnum":{"type":"string","enum":["legacy","new"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"$ref":"#/components/schemas/CreatedAt"},"tags":{"$ref":"#/components/schemas/Tags"},"type":{"$ref":"#/components/schemas/KeyTypeEnum"}},"required":["id","created_at","type","tags"]},"ListRealmConsumers":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsumerWithRealm"}},"meta":{"$ref":"#/components/schemas/CursorMeta"}},"required":["data","meta"]},"ConsumerWithRealm":{"description":"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.","type":"object","properties":{"id":{"description":"The Consumer ID.","type":"string","format":"uuid","example":"b9e81174-b5bb-4638-a3c3-8afe61a0abf8","readOnly":true},"username":{"description":"The unique username of the Consumer. You must send either this field or `custom_id` with the request.","type":"string","nullable":true},"custom_id":{"description":"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.","type":"string","nullable":true},"type":{"$ref":"#/components/schemas/ConsumerType"},"tags":{"$ref":"#/components/schemas/Tags"},"consumer_groups":{"$ref":"#/components/schemas/ConsumerGroups"},"created_at":{"$ref":"#/components/schemas/CreatedAt"},"updated_at":{"$ref":"#/components/schemas/UpdatedAt"},"realm_id":{"$ref":"#/components/schemas/UUID"}},"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"},"additionalProperties":false,"required":["id","username","custom_id","type","tags","consumer_groups","created_at","updated_at","realm_id"]},"ListRealms":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsumerRealm"}},"meta":{"$ref":"#/components/schemas/CursorMeta"}},"required":["data","meta"]},"ListConsumers":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CentralizedConsumer"}},"meta":{"$ref":"#/components/schemas/CursorMeta"}},"required":["data","meta"]},"ListKeys":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"meta":{"$ref":"#/components/schemas/CursorMeta"}},"required":["data","meta"]},"ConsumerRealm":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ttl":{"$ref":"#/components/schemas/RealmTTL"},"negative_ttl":{"$ref":"#/components/schemas/NegativeTTL"},"consumer_groups":{"$ref":"#/components/schemas/RealmConsumerGroups"},"allowed_control_planes":{"$ref":"#/components/schemas/AllowedControlPlanes"},"allow_all_control_planes":{"$ref":"#/components/schemas/AllowAllControlPlanes"},"created_at":{"$ref":"#/components/schemas/CreatedAt"},"updated_at":{"$ref":"#/components/schemas/UpdatedAt"}},"required":["id","name","allowed_control_planes","allow_all_control_planes","ttl","negative_ttl","consumer_groups","created_at","updated_at"]},"RealmReference":{"type":"object","properties":{"realm_id":{"type":"string"}},"required":["realm_id"]},"MoveConsumerRequest":{"type":"object","properties":{"target_realm_id":{"type":"string"}},"required":["target_realm_id"]},"ConsumerRealmCreateRequest":{"type":"object","properties":{"name":{"type":"string"},"allowed_control_planes":{"$ref":"#/components/schemas/AllowedControlPlanes"},"allow_all_control_planes":{"$ref":"#/components/schemas/AllowAllControlPlanes"},"ttl":{"$ref":"#/components/schemas/RealmTTL"},"negative_ttl":{"$ref":"#/components/schemas/NegativeTTL"},"consumer_groups":{"$ref":"#/components/schemas/RealmConsumerGroups"}},"additionalProperties":false,"required":["name"]},"UpdateConsumerPayload":{"type":"object","properties":{"username":{"$ref":"#/components/schemas/ConsumerUsername"},"custom_id":{"description":"Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database.","type":"string","minLength":1,"nullable":true},"consumer_groups":{"description":"A list of consumer groups that the Consumer is in.\nIf `consumer_groups` are provided on the Consumer object _and_ on the Realm, the Consumer will be placed in all defined consumer groups.\n","type":"array","items":{"type":"string","uniqueItems":true},"nullable":true,"title":"ConsumerGroups"},"type":{"$ref":"#/components/schemas/ConsumerType"},"tags":{"$ref":"#/components/schemas/Tags"}},"additionalProperties":false},"AllowAllControlPlanes":{"description":"Allow all control planes to use the realm. When this value is set it takes precedence on `allowed_control_planes`.\n","type":"boolean","nullable":false},"ConsumerRealmUpdateRequest":{"type":"object","properties":{"name":{"type":"string"},"allowed_control_planes":{"$ref":"#/components/schemas/AllowedControlPlanes"},"allow_all_control_planes":{"$ref":"#/components/schemas/AllowAllControlPlanes"},"consumer_groups":{"$ref":"#/components/schemas/RealmConsumerGroups"},"ttl":{"$ref":"#/components/schemas/RealmTTL"},"negative_ttl":{"$ref":"#/components/schemas/NegativeTTL"}},"additionalProperties":false},"ConsumerUsername":{"description":"The unique username of the Consumer.","type":"string","minLength":1},"ConsumerCustomID":{"description":"Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database.","type":"string","minLength":1},"RealmTTL":{"description":"The time in minutes that the Consumer will be cached in memory on a running Gateway if it is\nsuccessfully loaded from Konnect.\n","type":"integer","default":10,"minimum":5},"NegativeTTL":{"description":"If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a `negative_ttl`\nis set. The Gateway will not try to lookup the Consumer in Konnect for `negative_ttl` minutes.\n\nA Consumer will be cached for `negative_ttl` if they do not exist in the Realm, or if the provided credentials\nare invalid.\n","type":"integer","default":10,"minimum":5},"ConsumerCreateRequest":{"type":"object","properties":{"username":{"$ref":"#/components/schemas/ConsumerUsername"},"custom_id":{"$ref":"#/components/schemas/ConsumerCustomID"},"consumer_groups":{"$ref":"#/components/schemas/ConsumerGroups"},"type":{"$ref":"#/components/schemas/ConsumerType"},"tags":{"$ref":"#/components/schemas/Tags"}},"additionalProperties":false,"required":["username"]},"AllowedControlPlanes":{"description":"List of control plane ids that are allowed to use the realm. This is used when `allow_all_control_planes` value\nis set to false.\n","type":"array","items":{"type":"string","uniqueItems":true},"format":"set"},"ConsumerType":{"description":"Type of the consumer.\n","type":"string","default":"proxy","enum":["proxy","developer","admin","application"]},"Tags":{"type":"array","items":{"type":"string"},"uniqueItems":true},"ConsumerGroups":{"description":"A list of consumer groups that the Consumer is in.\nIf `consumer_groups` are provided on the Consumer object _and_ on the Realm, the Consumer will be placed in all defined consumer groups.\n","type":"array","items":{"type":"string","uniqueItems":true},"title":"ConsumerGroups"},"CreatedAt":{"description":"An ISO-8601 timestamp representation of entity creation date.","type":"string","format":"date-time","example":"2022-11-04T20:10:06.927Z","readOnly":true},"UpdatedAt":{"description":"An ISO-8601 timestamp representation of entity update date.","type":"string","format":"date-time","example":"2022-11-04T20:10:06.927Z","readOnly":true},"CentralizedConsumer":{"description":"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.","type":"object","properties":{"id":{"description":"The Consumer ID.","type":"string","format":"uuid","example":"b9e81174-b5bb-4638-a3c3-8afe61a0abf8","readOnly":true},"username":{"description":"The unique username of the Consumer. You must send either this field or `custom_id` with the request.","type":"string","nullable":true},"custom_id":{"description":"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.","type":"string","nullable":true},"type":{"$ref":"#/components/schemas/ConsumerType"},"tags":{"$ref":"#/components/schemas/Tags"},"consumer_groups":{"$ref":"#/components/schemas/ConsumerGroups"},"created_at":{"$ref":"#/components/schemas/CreatedAt"},"updated_at":{"$ref":"#/components/schemas/UpdatedAt"}},"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"},"additionalProperties":false,"required":["id","username","custom_id","type","tags","consumer_groups","created_at","updated_at"]},"UUID":{"description":"Contains a unique identifier used for this resource.","type":"string","format":"uuid","example":"5f9fd312-a987-4628-b4c5-bb4f4fddd5f7","readOnly":true},"CursorMetaPage":{"type":"object","properties":{"first":{"description":"URI to the first page","type":"string","format":"path"},"last":{"description":"URI to the last page","type":"string","format":"path"},"next":{"description":"URI to the next page","type":"string","format":"path","nullable":true},"previous":{"description":"URI to the previous page","type":"string","format":"path","nullable":true},"size":{"description":"Requested page size","type":"number","example":10}},"required":["size","next","previous"]},"CursorMeta":{"description":"Pagination metadata.","type":"object","properties":{"page":{"$ref":"#/components/schemas/CursorMetaPage"}},"required":["page"]},"RealmConsumerGroups":{"description":"A list of consumer groups to automatically add to any consumers created within this Realm.\nIf `consumer_groups` are provided on the Consumer object _and_ on the Realm, the Consumer will be placed in all defined consumer groups.\n","type":"array","items":{"type":"string","uniqueItems":true},"format":"set","title":"RealmConsumerGroups"},"BaseError":{"description":"standard error","type":"object","properties":{"status":{"description":"The HTTP status code of the error. Useful when passing the response\nbody to child properties in a frontend UI. Must be returned as an integer.\n","type":"integer","readOnly":true},"title":{"description":"A short, human-readable summary of the problem. It should not\nchange between occurences of a problem, except for localization.\nShould be provided as \"Sentence case\" for direct use in the UI.\n","type":"string","readOnly":true},"type":{"description":"The error type.","type":"string","readOnly":true},"instance":{"description":"Used to return the correlation ID back to the user, in the format\nkong:trace:<correlation_id>. This helps us find the relevant logs\nwhen a customer reports an issue.\n","type":"string","readOnly":true},"detail":{"description":"A human readable explanation specific to this occurence of the problem.\nThis field may contain request/entity data to help the user understand\nwhat went wrong. Enclose variable values in square brackets. Should be\nprovided as \"Sentence case\" for direct use in the UI.\n","type":"string","readOnly":true}},"required":["status","title","instance","detail"],"title":"Error"},"InvalidRules":{"description":"invalid parameters rules","type":"string","enum":["required","is_array","is_base64","is_boolean","is_date_time","is_integer","is_null","is_number","is_object","is_string","is_uuid","is_fqdn","is_arn","unknown_property","missing_reference","is_label","matches_regex","invalid","is_supported_network_availability_zone_list","is_supported_network_cidr_block","is_supported_provider_region","type"],"nullable":true,"readOnly":true},"InvalidParameterStandard":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"$ref":"#/components/schemas/InvalidRules"},"source":{"type":"string","example":"body"},"reason":{"type":"string","example":"is a required field","readOnly":true}},"additionalProperties":false,"required":["field","reason"]},"InvalidParameterMinimumLength":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["min_length","min_digits","min_lowercase","min_uppercase","min_symbols","min_items","min"],"nullable":false,"readOnly":true},"minimum":{"type":"integer","example":8},"source":{"type":"string","example":"body"},"reason":{"type":"string","example":"must have at least 8 characters","readOnly":true}},"additionalProperties":false,"required":["field","reason","rule","minimum"]},"InvalidParameterMaximumLength":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["max_length","max_items","max"],"nullable":false,"readOnly":true},"maximum":{"type":"integer","example":8},"source":{"type":"string","example":"body"},"reason":{"type":"string","example":"must not have more than 8 characters","readOnly":true}},"additionalProperties":false,"required":["field","reason","rule","maximum"]},"InvalidParameterChoiceItem":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["enum"],"nullable":false,"readOnly":true},"reason":{"type":"string","example":"is a required field","readOnly":true},"choices":{"type":"array","items":{},"minItems":1,"nullable":false,"readOnly":true,"uniqueItems":true},"source":{"type":"string","example":"body"}},"additionalProperties":false,"required":["field","reason","rule","choices"]},"InvalidParameterDependentItem":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["dependent_fields"],"nullable":true,"readOnly":true},"reason":{"type":"string","example":"is a required field","readOnly":true},"dependents":{"type":"array","items":{},"nullable":true,"readOnly":true,"uniqueItems":true},"source":{"type":"string","example":"body"}},"additionalProperties":false,"required":["field","rule","reason","dependents"]},"InvalidParameters":{"description":"invalid parameters","type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/InvalidParameterStandard"},{"$ref":"#/components/schemas/InvalidParameterMinimumLength"},{"$ref":"#/components/schemas/InvalidParameterMaximumLength"},{"$ref":"#/components/schemas/InvalidParameterChoiceItem"},{"$ref":"#/components/schemas/InvalidParameterDependentItem"}]},"minItems":1,"nullable":false,"uniqueItems":true},"BadRequestError":{"allOf":[{"$ref":"#/components/schemas/BaseError"},{"type":"object","required":["invalid_parameters"],"properties":{"invalid_parameters":{"$ref":"#/components/schemas/InvalidParameters"}}}]},"NotFoundError":{"allOf":[{"$ref":"#/components/schemas/BaseError"},{"type":"object","properties":{"status":{"example":404},"title":{"example":"Not Found"},"type":{"example":"https://httpstatuses.com/404"},"instance":{"example":"kong:trace:1234567890"},"detail":{"example":"Not found"}}}]}},"examples":{"ListRealmConsumers":{"value":{"data":[{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","realm_id":"55ec70a4-d197-495c-8f3e-c0a1199d1da4","username":"Bob","custom_id":"Dyl4N","type":"application","tags":["one","two"],"consumer_groups":["gold","silver"],"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}],"meta":{"page":{"size":1,"previous":null,"next":"/v1/realm-consumers?page%5Bafter%5D=f1kZXVdYF0VFUEcBGA1%2BGUEAMV5CDBRYSlwKUF9fHRREQ10XFQ%3D%3D"}}}},"ListRealms":{"value":{"data":[{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","name":"Jason","ttl":15,"negative_ttl":10,"consumer_groups":["api-developer"],"allowed_control_planes":["55ec70a4-d197-495c-8f3e-c0a1199d1da4"],"allow_all_control_planes":false,"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}],"meta":{"page":{"size":1,"previous":null,"next":"/v1/realms?page%5Bafter%5D=f1kZXVdYF0VFUEcBGA1%2BGUEAMV5CDBRYSlwKUF9fHRREQ10XFQ%3D%3D"}}}},"ListConsumers":{"value":{"data":[{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","username":"Bob","custom_id":"Dyl4N","type":"application","tags":["one","two"],"consumer_groups":["gold","silver"],"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}],"meta":{"page":{"size":1,"previous":null,"next":"/v1/realms/4e410025-b357-4cf1-82e1-4871f3f43532/consumers?page%5Bafter%5D=f1kZXVdYF0VFUEcBGA1%2BGUEAMV5CDBRYSlwKUF9fHRREQ10XFQ%3D%3D"}}}},"ListConsumerKeys":{"value":{"data":[{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","created_at":"2023-03-20T09:29:14.52Z","tags":["one","two"],"type":"new"}],"meta":{"page":{"size":1,"previous":null,"next":"/v1/realms/4e410025-b357-4cf1-82e1-4871f3f43532/consumers/2cec70a4-d197-495c-8f3e-c0a1199d1da4/keys?page%5Bafter%5D=f1kZXVdYF0VFUEcBGA1%2BGUEAMV5CDBRYSlwKUF9fHRREQ10XFQ%3D%3D"}}}},"ApiKey":{"value":{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","created_at":"2023-03-20T09:29:14.52Z","tags":["one","two"],"type":"new"}},"Realm":{"value":{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","name":"Jason","ttl":15,"negative_ttl":10,"consumer_groups":["api-developer"],"allowed_control_planes":["55ec70a4-d197-495c-8f3e-c0a1199d1da4"],"allow_all_control_planes":false,"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}},"Consumer":{"value":{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","username":"Bob","custom_id":"Dyl4N","type":"application","tags":["one","two"],"consumer_groups":["gold","silver"],"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}},"CreateApiKeyResult":{"value":{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","type":"new","secret":"1_7YQ4eVaGyskxnMuvLFwm4_NfsDNyzHccHgD741EjpMGMZLLQUbQtDU92nGzpYgNWr8qs2rA_65ef014d","tags":["one","two"],"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}},"CreateApiKeyResultLegacy":{"value":{"id":"2cec70a4-d197-495c-8f3e-c0a1199d1da4","type":"legacy","secret":"S€CR€T","tags":["one","two"],"created_at":"2023-03-20T09:29:14.52Z","updated_at":"2023-03-21T09:29:14.52Z"}},"NotFoundExample":{"value":{"status":404,"title":"Not Found","instance":"kong:trace:6816496025408232265","detail":"Not Found"}}},"requestBodies":{"UpdateConsumer":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConsumerPayload"},"examples":{"UpdateConsumerPayload":{"value":{"username":"Jason"}}}}}},"CreateApiKey":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyPayload"},"examples":{"New":{"value":{"type":"new"}},"Legacy":{"value":{"type":"legacy","secret":"S€CR€T"}}}}}},"UpdateConsumerRealm":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerRealmUpdateRequest"},"examples":{"Update":{"value":{"name":"MyKingdom"}}}}}},"CreateConsumerRealm":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerRealmCreateRequest"},"examples":{"CreateRealm":{"value":{"name":"kingdom"}}}}}},"CreateConsumer":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerCreateRequest"},"examples":{"CreateConsumer":{"value":{"username":"J4son"}}}}}},"MoveConsumer":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveConsumerRequest"},"examples":{"Move":{"value":{"target_realm_id":"77fd4d02-5d87-4f76-90a9-1bd6ce152c36"}}}}}}},"responses":{"CreateConsumerResponse":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralizedConsumer"},"examples":{"Consumer":{"$ref":"#/components/examples/Consumer"}}}}},"CreateConsumerRealmResponse":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerRealm"},"examples":{"Realm":{"$ref":"#/components/examples/Realm"}}}}},"MoveConsumerResponse":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealmReference"}}}},"NotFound":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/NotFoundError"},"examples":{"NotFoundExample":{"$ref":"#/components/examples/NotFoundExample"}}}}}},"securitySchemes":{"systemAccountAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Token","description":"The system account access token is meant for automations and integrations that are not directly associated with a human identity.\nYou can generate a system account Access Token by creating a system account and then obtaining a system account access token for that account.\nThe access token must be passed in the header of a request, for example:\n`curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer spat_i2Ej...'`\n"},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Token","description":"The personal access token is meant to be used as an alternative to basic-auth when accessing Konnect via APIs.\nYou can generate a Personal Access Token (PAT) from the [personal access token page](https://cloud.konghq.com/global/account/tokens/) in the Konnect dashboard.\nThe PAT token must be passed in the header of a request, for example:\n`curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer kpat_xgfT...'`\n"},"konnectAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"The Konnect access token is meant to be used by the Konnect dashboard and the decK CLI authenticate with.\n"}}},"tags":[{"name":"Realms","description":"Use a realm to group consumers around an identity, defined by organizational boundaries, such as a production realm or a development realm. Realms are connected to a [geographic region](https://docs.konghq.com/konnect/geo/) in Konnect. Centrally managed consumers defined in realms can be used across multiple control planes.\n"},{"name":"Centrally Managed Consumers","description":"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.\n"},{"name":"Centrally Managed Keys","description":"Centrally managed consumers use key-auth mechanism to authenticate consumers. Keys refer to the API key credential used by the consumer to authenticate to your services. \n"}],"security":[{"systemAccountAccessToken":[]},{"personalAccessToken":[]},{"konnectAccessToken":[]}]}
```
