From 136fe72b2dd2a4d717d412afec39af2d5de56af2 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 21 Nov 2024 10:37:47 -0500 Subject: [PATCH] move things for 3.9 --- api-specs/Gateway-EE/3.8/kong-ee.yaml | 16346 ++++++++++++++++++++++ api-specs/Gateway-EE/3.9/kong-ee.yaml | 16346 ++++++++++++++++++++++ api-specs/Gateway-OSS/3.8/kong-oss.yaml | 8083 +++++++++++ api-specs/Gateway-OSS/3.9/kong-oss.yaml | 8083 +++++++++++ 4 files changed, 48858 insertions(+) create mode 100644 api-specs/Gateway-EE/3.8/kong-ee.yaml create mode 100644 api-specs/Gateway-EE/3.9/kong-ee.yaml create mode 100644 api-specs/Gateway-OSS/3.8/kong-oss.yaml create mode 100644 api-specs/Gateway-OSS/3.9/kong-oss.yaml diff --git a/api-specs/Gateway-EE/3.8/kong-ee.yaml b/api-specs/Gateway-EE/3.8/kong-ee.yaml new file mode 100644 index 000000000000..cb3bf230d528 --- /dev/null +++ b/api-specs/Gateway-EE/3.8/kong-ee.yaml @@ -0,0 +1,16346 @@ +components: + parameters: + pagination-offset: + description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources + in: query + name: offset + schema: + type: string + pagination-size: + description: Number of resources to be returned. + in: query + name: size + schema: + default: 100 + maximum: 1000 + minimum: 1 + type: integer + pagination-tags-filter: + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using `,` to mean AND or using `/` to mean OR. + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + certificate_name_or_id: + name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + sni_name_or_id: + name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + tag: + name: tags + in: path + required: true + schema: + type: string + example: example + description: Tags are strings associated to entities in Kong. + log_level: + name: log_level + in: path + required: true + schema: + type: string + enum: + - info + - notice + - warn + - error + - crit + example: warn + description: Log levels are set in Kong's configuration. Log levels increase in order of their severity + target_id_or_target: + name: target_id_or_target + in: path + required: true + schema: + type: string + example: 'example.com:8000' + description: The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. + vault_id_or_prefix: + name: vault_id_or_prefix + in: path + required: true + schema: + type: string + example: env + description: The unique identifier or the prefix of the Vault to retrieve. + plugin_id: + name: plugin_id + in: path + required: true + schema: + type: string + example: response-ratelimiting + description: The unique identifier of the plugin to create or update. + upstream_id_or_name: + name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + key-set_id_or_name: + name: key-set_id_or_name + in: path + required: true + schema: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + description: The unique identifier or the `name` attribute of the Key Set that should be associated to the newly-created Key. + route_id_or_name: + name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + key_id_or_name: + name: key_id_or_name + in: path + required: true + schema: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725 + description: The unique identifier or the name of the Key to retrieve. + ca_certificate_id: + name: ca_certificate_id + description: ID of the related certificate + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + certificate_id: + name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + description: The unique identifier of the Certificate to retrieve. + service_id_or_name: + name: service_id_or_name + description: ID **or** name of the service to lookup + example: test-service + in: path + required: true + schema: + type: string + group_name_or_id: + name: group_name_or_id + in: path + required: true + schema: + anyOf: + - type: string + example: my_group + - type: string + example: 84a73fb8-50fc-44a7-a4d5-aa17728ee83f + type: string + example: my_group + description: The name or UUID of the consumer group. + group_name: + name: group_name + in: path + required: true + schema: + type: string + example: My-Group + description: A unique name for the consumer group you want to create. + consumer_name_or_id: + name: consumer_name_or_id + in: path + required: true + schema: + type: string + description: The name or UUID of the consumer to remove. + consumer_group_name_or_id: + name: consumer_group_name_or_id + in: path + required: true + schema: + type: string + description: The name or UUID of the consumer group to remove. + consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + license-id: + name: license-id + in: path + required: true + schema: + type: string + example: 30b4edb7-0847-4f65-af90-efbed8b0161f + description: The license's unique ID. + workspace_id_or_name: + name: workspace_id_or_name + in: path + required: true + schema: + type: string + example: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + description: ID or name of the workspace to look up. + workspace: + name: workspace + in: path + required: true + schema: + type: string + example: team-a + description: Name or ID of workspace + Gatewayapi_Consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + Gatewayapi_Pagination-tags-filter: + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using `,` to mean AND or using `/` to mean OR. + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + filter_chain_id: + name: filter_chain_id + in: path + required: true + schema: + type: string + description: The unique identifier of the filter chain to retrieve. + beforeAuditLogFilter: + name: before_audit_log_filter + in: query + required: false + schema: + $ref: '#/components/schemas/RequestTimestampFilterSchema' + description: | + Before filter could be used to request audit log data that was recorded before certain time (exclusive). + It can either be a timestamp as Unix Epoch or a string following RFC3339 Schema (without fractions of a second) - ex: '2024-04-25T15:03:24Z' + afterAuditLogFilter: + name: after_audit_log_filter + in: query + required: false + schema: + $ref: '#/components/schemas/RequestTimestampFilterSchema' + description: | + After filter could be used to request audit log data that was recorded after certain time (inclusive). + It can either be a timestamp as Unix Epoch or a string following RFC3339 Schema (without fractions of a second) - ex: '2024-04-25T15:03:24Z' + schemas: + UnauthorizedError: + type: object + properties: + status: + type: integer + message: + type: string + required: + - status + - message + CA-Certificate: + description: A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f260 + type: object + properties: + cert: + description: PEM-encoded public certificate of the CA. + type: string + cert_digest: + description: SHA256 hex digest of the public certificate. This field is read-only and it cannot be set by the caller, the value is automatically computed. + type: string + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: tag + Certificate: + description: A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string according to the following order, main certificate on the top, followed by any intermediates. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + properties: + cert: + description: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + cert_alt: + description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + key: + description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + key_alt: + description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + snis: + description: > + A list of SNIs associated with the certificate. + type: array + items: + type: string + format: hostname + type: object + Consumer: + 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. + example: + custom_id: '4200' + id: 8a388226-20e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + 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 + id: + type: string + tags: + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + username: + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + type: string + type: object + x-examples: + Consumer Object: + custom_id: '4200' + id: 8a388226-80e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + Key: + description: A Key object holds a representation of asymmetric keys in various formats. When Kong or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + example: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + jwk: + description: A JSON Web Key represented as a string. + type: string + kid: + description: A unique identifier for a key. + type: string + name: + description: The name to associate with the given keys. + type: string + pem: + description: A keypair in PEM format. + properties: + private_key: + type: string + public_key: + type: string + type: object + set: + additionalProperties: false + description: The id (an UUID) of the key-set with which to associate the key. + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Key-set: + example: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + tags: + - idp-keys + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + name: + type: string + tags: + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Key-set + Plugin: + description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). When adding a Plugin Configuration to a Service, every request made by a client to that Service will run said Plugin. If a Plugin needs to be tuned to different values for some specific Consumers, you can do so by creating a separate plugin instance that specifies both the Service and the Consumer, through the `service` and `consumer` fields. + example: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + properties: + config: + description: The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/). + type: object + consumer: + additionalProperties: false + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer. + properties: + id: + type: string + type: object + consumer_group: + additionalProperties: false + description: If set, the plugin will activate only for requests where the specified consumer group has been authenticated. (Note that some plugins can not be restricted to consumers groups this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer Groups + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the plugin is applied. + type: boolean + id: + type: string + name: + description: "The name of the plugin that's going to be added. The plugin must be installed in every Kong instance separately." + type: string + ordering: + type: object + protocols: + default: + - grpc + - grpcs + - http + - https + description: A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `tcp` and `tls`. + items: + type: string + type: array + route: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the Route being used. + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched. + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the plugin for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Route: + description: Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service. The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the Route. + example: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + destinations: + description: A list of IP destinations of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + properties: + default: {} + type: object + type: array + headers: + description: One or more lists of values indexed by header name that will cause this Route to match if present in the request. The `Host` header cannot be used with this `attribute:` hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression. + type: object + hosts: + description: A list of domain names that match this Route. Note that the hosts value is case sensitive. + items: + type: string + type: array + https_redirect_status_code: + default: 426 + description: The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. This config applies only if the Route is configured to only accept the `https` protocol. + type: integer + id: + type: string + methods: + description: A list of HTTP methods that match this Route. + items: + type: string + type: array + name: + description: The name of the Route. Route names must be unique, and they are case sensitive. For example, there can be two different Routes named "test" and "Test". + type: string + path_handling: + default: v0 + description: Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. + type: string + paths: + description: A list of paths that match this Route. + items: + type: string + type: array + preserve_host: + default: false + description: "When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the service's `host`." + type: boolean + protocols: + default: + - http + - https + description: An array of the protocols this Route should allow. See the [Route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error. + items: + type: string + type: array + regex_priority: + default: 0 + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + type: integer + request_buffering: + default: true + description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. + type: boolean + response_buffering: + default: true + description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. + type: boolean + service: + additionalProperties: false + description: The Service this route is associated to. This is where the route proxies traffic to. + properties: + id: + type: string + type: object + expression: + description: The route expression used for advanced routing scenarios. This field is used to evaluate route matches based on complex criteria beyond the standard routing fields. + type: string + priority: + description: A number used to specify the matching order for expression routes. The higher the `priority`, the sooner a route will be evaluated. This field is ignored unless `expression` field is set. The value must be between 0 and 2^46 - 1. + type: integer + default: 0 + snis: + description: A list of SNIs that match this route when using stream routing. + items: + type: string + type: array + sources: + description: A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + properties: + default: {} + type: object + type: array + strip_path: + default: true + description: When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL. + type: boolean + tags: + description: An optional set of strings associated with the route for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + SNI: + description: An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate. + example: + certificate: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + id: 36c4566c-14cc-4132-9011-4139fcbbe50a + name: some.example.org + properties: + certificate: + additionalProperties: false + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + name: + description: The SNI name to associate with the given certificate. + type: string + tags: + description: An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Service: + description: Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc. The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its `protocol`, `host`, `port` and `path` individually. Services are associated to routes (a Service can have many routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a route is matched, Kong proxies the request to its associated Service. See the [Proxy Reference][proxy-reference] for a detailed explanation of how Kong proxies traffic. + example: + host: example.internal + id: 49fd316e-c457-481c-9fc7-8079153e4f3c + name: example-service + path: / + port: 80 + protocol: http + properties: + ca_certificates: + description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream servers TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). + items: + type: string + type: array + client_certificate: + additionalProperties: false + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + type: object + connect_timeout: + default: 60000 + description: The timeout in milliseconds for establishing a connection to the upstream server. + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the Service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). + type: boolean + host: + description: The host of the upstream server. Note that the host value is case sensitive. + type: string + id: + type: string + name: + description: The Service name. + type: string + path: + description: The path to be used in requests to the upstream server. + type: string + port: + default: 80 + description: The upstream server port. + type: integer + protocol: + default: http + description: The protocol used to communicate with the upstream. + type: string + read_timeout: + default: 60000 + description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. + type: integer + retries: + default: 5 + description: The number of retries to execute upon failure to proxy. + type: integer + tags: + description: An optional set of strings associated with the Service for grouping and filtering. + items: + type: string + type: array + tls_verify: + description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected. + type: boolean + tls_verify_depth: + description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected. + type: integer + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + url: + description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses. + type: string + write_timeout: + default: 60000 + description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. + type: integer + type: object + title: Service + Target: + description: A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. To disable a target, post a new one with `weight=0`; alternatively, use the `DELETE` convenience method to accomplish the same. The current target object definition is the one with the latest `created_at`. + example: + id: 089292a7-ba3d-4d88-acf0-97b4b2e2621a + target: 203.0.113.42 + upstream: + id: 5f1d7e76-2fed-4806-a6af-869984f025cb + weight: 100 + properties: + created_at: + description: Unix epoch when the resource was created. + type: number + id: + type: string + tags: + description: An optional set of strings associated with the Target for grouping and filtering. + items: + type: string + type: array + target: + description: The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record. + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: number + upstream: + additionalProperties: false + properties: + id: + type: string + type: object + weight: + default: 100 + description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + type: object + Upstream: + description: The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + example: + algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + properties: + algorithm: + default: round-robin + description: Which load balancing algorithm to use. + type: string + client_certificate: + additionalProperties: false + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + hash_fallback: + default: none + description: What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`. + type: string + hash_fallback_header: + description: The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. + type: string + hash_fallback_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + type: string + hash_fallback_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + type: string + hash_on: + default: none + description: What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. + type: string + hash_on_cookie: + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + type: string + hash_on_cookie_path: + default: / + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + type: string + hash_on_header: + description: The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. + type: string + hash_on_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + type: string + hash_on_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + type: string + healthchecks: + properties: + active: + properties: + concurrency: + default: 10 + type: integer + headers: + type: object + healthy: + properties: + http_statuses: + default: + - 200 + - 302 + items: + type: integer + type: array + interval: + default: 0 + type: number + successes: + default: 0 + type: integer + type: object + http_path: + default: / + type: string + https_sni: + type: string + https_verify_certificate: + default: true + type: boolean + timeout: + default: 1 + type: number + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + items: + type: integer + type: array + interval: + default: 0 + type: number + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + passive: + properties: + healthy: + properties: + http_statuses: + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + items: + type: integer + type: array + successes: + default: 0 + type: integer + type: object + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 500 + - 503 + items: + type: integer + type: array + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + threshold: + default: 0 + type: number + type: object + host_header: + description: The hostname to be used as `Host` header when proxying requests through Kong. + type: string + id: + type: string + name: + description: This is a hostname, which must be equal to the `host` of a Service. + type: string + slots: + default: 10000 + description: The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`. + type: integer + tags: + description: An optional set of strings associated with the Upstream for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + use_srv_name: + default: false + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`. + type: boolean + type: object + Vault: + description: Vault entities are used to configure different Vault connectors. Examples of Vaults are Environment Variables, HashiCorp Vault and AWS Secrets Manager. Configuring a Vault allows referencing the secrets with other entities. For example a certificate entity can store a reference to a certificate and key, stored in a vault, instead of storing the certificate and key within the entity. This allows a proper separation of secrets and configuration and prevents secret sprawl. + example: + config: + prefix: vaults.config.resurrect_ttl + description: environment variable based vault + id: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + name: env + tags: + - foo + - bar + properties: + config: + description: The configuration properties for the Vault which can be found on the [vaults documentation page](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + type: object + properties: + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + enum: + - vaults.config.resurrect_ttl + - vaults.config.neg_ttl + - vaults.config.ttl + required: + - prefix + created_at: + description: Unix epoch when the resource was created. + type: integer + description: + description: The description of the Vault entity. + type: string + id: + type: string + name: + description: The name of the vault that's going to be added. The vault implementation must be installed in every Kong instance. + type: string + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + tags: + description: An optional set of strings associated with the Vault for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Workspace: + type: object + properties: + comment: + type: string + config: + type: object + properties: + meta: + type: object + portal: + default: false + type: boolean + description: Portal enabled + portal_access_request_email: + type: boolean + portal_application_request_email: + type: boolean + portal_application_status_email: + type: boolean + portal_approved_email: + type: boolean + portal_auth: + type: string + portal_auth_conf: + type: string + portal_auto_approve: + type: boolean + portal_cors_origins: + type: array + items: + type: string + portal_developer_meta_fields: + default: '[{"label":"Full Name","title":"full_name","validator":{"required":true,"type":"string"}}]' + type: string + portal_emails_from: + type: string + portal_emails_reply_to: + type: string + portal_invite_email: + type: boolean + portal_is_legacy: + type: boolean + portal_reset_email: + type: boolean + portal_reset_success_email: + type: boolean + portal_session_conf: + type: string + portal_smtp_admin_emails: + type: array + items: + type: string + portal_token_exp: + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + description: The unique UUID for this resource. + meta: + type: object + properties: + color: + type: string + thumbnail: + type: string + name: + type: string + x-examples: + Example 1: + comment: string + config: + meta: {} + portal: false + portal_access_request_email: true + portal_application_request_email: true + portal_application_status_email: true + portal_approved_email: true + portal_auth: string + portal_auth_conf: string + portal_auto_approve: true + portal_cors_origins: + - string + portal_developer_meta_fields: >- + [{"label":"Full Name","title":"full_name","validator":{"required":true,"type":"string"}}] + portal_emails_from: string + portal_emails_reply_to: string + portal_invite_email: true + portal_is_legacy: true + portal_reset_email: true + portal_reset_success_email: true + portal_session_conf: string + portal_smtp_admin_emails: + - string + portal_token_exp: 0 + created_at: 0 + id: string + meta: + color: string + thumbnail: string + name: string + description: Workspaces provide a way to segment Kong entities. + pagination-offset-response: + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + type: string + Filter-chains: + type: object + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: my-chain + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + - name: go-rate-limiting + enabled: true + config: '{ "minute": 30 }' + - name: rust-response-transformer + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: + - my-tag + description: A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + title: Filter-chains + properties: + id: + type: string + description: The unique identifier or the name attribute of the route that should be associated to the newly created filter chain. + example: ce44eef5-41ed-47f6-baab-f725cecf98c7 + format: uuid + name: + type: string + description: | + The name of the filter chain. + example: my-chain + created_at: + type: integer + example: 1422386534 + updated_at: + type: integer + example: 1422386534 + enabled: + type: boolean + description: | + Whether the filter chain is applied. Default: true. + default: true + route: + description: The route to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `route.id=` or `route.name=`. In JSON format, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: The service to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `service.id=` or `service.name=`. In JSON format, use `"service":{"id":""}` or `"service":{"name":""}`. + example: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + type: array + description: An array of filter definitions. Each filter is an object containing a mandatory name, an optional config, and a boolean enabled setting. + items: + type: object + properties: + name: + type: string + description: | + The name of the filter + example: go-rate-limiting + enabled: + type: boolean + description: Enable the filter + config: + type: string + description: configuration filter headers + example: '{ \"minute\": 30 }' + tags: + type: array + items: + type: string + RequestTimestampFilterSchema: + oneOf: + - type: string + pattern: '^(\d+|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)$' + - type: integer + responses: + HTTP401Error: + content: + application/json: + examples: + DuplicateApiKey: + summary: Duplicate API key found + value: + message: Duplicate API key found + status: 401 + InvalidAuthCred: + summary: Invalid authentication credentials + value: + message: Unauthorized + status: 401 + NoAPIKey: + summary: No API key found + value: + message: No API key found in request + status: 401 + schema: + $ref: '#/components/schemas/UnauthorizedError' + description: Unauthorized + tags-response: + description: Tags response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - entity_name: services + entity_id: acf60b10-125c-4c1a-bffe-6ed55daefba4 + tag: s1 + offset: c47139f3-d780-483d-8a97-17e9adc5a7ab + next: /tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab + properties: + data: + type: array + items: + type: object + properties: + entity_name: + type: string + example: services + description: The name of the entity that corresponds to a tag + entity_id: + type: string + example: c87440e1-0496-420b-b06f-dac59544bb6c + description: The unique ID for the entity that is attached to the tag + tag: + type: string + example: example + description: The tag + offset: + type: string + example: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + next: + type: string + example: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + examples: + Tags response: + value: + data: + - entity_name: services + entity_id: c87440e1-0496-420b-b06f-dac59544bb6c + tag: example + offset: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + next: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + key-set-response: + description: Key set object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - idp-keys + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + id: + type: string + example: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + created_at: + type: integer + description: Unix epoch when the resource was last created. + example: 1422386534 + updated_at: + type: integer + description: | + Unix epoch when the resource was last updated. + example: 1422386534 + tags: + type: array + description: | + The name to associate with the given key-set. + items: + type: string + next: + type: string + description: | + Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + example: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + examples: + example: + value: + id: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: my-key_set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - string + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + plugin-response: + description: A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. + content: + application/json: + schema: + type: object + properties: + id: + type: string + name: + type: string + description: The name of the plugin thats going to be added. Currently, the plugin must be installed in every Kong instance separately. + example: rate-limiting + created_at: + type: integer + description: Unix epoch when the resource was created. + route: + type: string + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default, `null`.With form-encoded, the notation is `route.id=` or `route.name=`. With JSON, use `route:{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique within a workspace for Kong Gateway Enterprise. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the plugin for grouping and filtering. + items: + type: string + ordering: + type: object + description: | + Describes a dependency to another plugin to determine plugin ordering during the access phase. + - `before`: The plugin will be executed before a specified plugin or list of plugins. + - `after`: The plugin will be executed after a specified plugin or list of plugins. + properties: + before: + type: array + items: + type: string + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + examples: + Plugin response: + value: + data: + - id: 02621eee-8309-4bf6-b36b-a82017a5393e + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + - id: 66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - tcp + - tls + enabled: true + tags: + - admin + - high-priority + - critical + ordering: + after: + - plugin-name + next: 'http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + sni-response: + description: SNI response object + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + name: my-sni + created_at: 1422386534 + tags: + - user-level + - low-priority + certificate: + id: a3ad71a8-6685-4b03-a101-980a953544f6 + - id: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: my-sni + created_at: 1422386534 + tags: + - admin + - high-priority + - critical + certificate: + id: 4e8d95d4-40f2-4818-adcb-30e00c349618 + next: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + description: Array of SNIs + items: + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + description: The unique identifier or the name attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + name: + type: string + description: | + The SNI name to associate with the given certificate. + example: my-sni + created_at: + type: integer + example: 1422386534 + description: | + Unix epoch when the resource was created. + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + certificate: + type: object + description: | + The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + properties: + id: + type: string + example: 2e013e8-7623-4494-a347-6d29108ff68b + description: The unique identifier or the name attribute of the Certificate whose SNIs + next: + type: string + example: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + consumer-response-data: + description: The consumer object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + - id: 01c23299-839c-49a5-a6d5-8864c09184af + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier or the name attribute of the consumer. + example: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1422386534 + username: + type: string + description: The unique username of the consumer. You must send either this field or` custom_i`d with the request. + example: my-username + custom_id: + type: string + 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. + example: my-custom-id + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + example: admin + next: + type: string + description: Pagination information + example: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + consumer_group_response: + description: The consumer group response body + content: + application/json: + schema: + type: object + properties: + data: + type: array + description: The data array contains consumer group objects + items: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1719859003 + id: + type: string + description: The UUID of the consumer group + example: 0d8f5353-8dd2-4013-859a-21510b970a64 + name: + type: string + description: The name of the consumer group + example: group2 + tags: + type: array + description: An optional set of strings associated with the consumer group for grouping and filtering. + items: + type: string + example: example_tag + updated_at: + type: integer + description: Unix epoch when the resource was last updated. + example: 1719859003 + next: + type: string + description: Link to the next page of results, if applicable + example: null + x-examples: + Example 1: + data: + - created_at: 1719859003 + id: 0d8f5353-8dd2-4013-859a-21510b970a64 + name: group2 + tags: [] + updated_at: 1719859003 + - created_at: 1719858982 + id: 7012a570-e372-4280-92db-7fbbe4af80bb + name: group1 + tags: [] + updated_at: 1719858982 + - created_at: 1719859346 + id: 9faf2f1b-2110-4690-8b64-c70dc14aa51a + name: group3 + tags: null + updated_at: 1719859346 + next: null + Consumer group example: + data: + - created_at: 1719859003 + id: 0d8f5353-8dd2-4013-859a-21510b970a64 + name: group2 + tags: [] + updated_at: 1719859003 + next: null + add_consumer_to_group_response: + description: The object returns information about the consumer and the group + content: + application/json: + schema: + type: object + x-examples: + Example 1: + consumer: + created_at: 1638918560 + custom_id: null + id: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + tags: null + type: 0 + username: BarryAllen + username_lower: barryallen + consumer_groups: + - created_at: 1638918476 + id: e2c3f16e-22c7-4ef4-b6e4-ab25c522b339 + name: JL + tags: null + properties: + consumer: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1638918560 + custom_id: + type: string + 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. + nullable: true + id: + type: string + description: The UUID for the consumer + tags: + type: object + description: An optional set of strings associated with consumer group for grouping and filtering. + nullable: true + type: + type: integer + default: 0 + example: 0 + username: + type: string + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + username_lower: + type: string + description: A lowercase representation of the username + consumer_groups: + type: array + items: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + id: + type: string + description: The UUID for the consumer group + name: + type: string + description: The name of the consumer group + tags: + type: object + description: An optional set of strings associated with consumer group for grouping and filtering. + nullable: true + examples: + Example: + value: + consumer: + created_at: 0 + custom_id: null + id: string + tags: null + type: 0 + username: string + username_lower: string + consumer_groups: + - created_at: 0 + id: string + name: string + tags: + red: null + consumer_response: + description: A consumer response object + content: + application/json: + schema: + type: object + properties: + data: + type: array + description: The data array contains consumer objects + items: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1719859293 + custom_id: + type: string + description: Custom ID of the consumer + example: consumer_id3 + id: + type: string + example: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + description: The consumer ID + tags: + type: array + description: Tags associated with the consumer + items: + type: string + example: test + type: + type: integer + default: 0 + example: 0 + updated_at: + type: integer + description: Unix epoch when the resource was last updated. + example: 1719859293 + username: + type: string + example: consumer3 + description: The username of the consumer + username_lower: + type: string + example: consumer3 + description: Lowercase representation of the consumer username. + next: + type: string + description: Link to the next page of results, if applicable + example: null + x-examples: + Example 1: + data: + - created_at: 1719859293 + custom_id: consumer_id3 + id: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + tags: null + type: 0 + updated_at: 1719859293 + username: consumer3 + username_lower: consumer3 + - created_at: 1719858943 + custom_id: consumer_id + id: 73b74f15-5185-4b16-a2fc-3c2fd834ba6c + tags: null + type: 0 + updated_at: 1719858943 + username: consumer + username_lower: consumer + - created_at: 1719858965 + custom_id: consumer_id2 + id: f9383372-7bf4-4275-8bbc-4f89d7a38a23 + tags: null + type: 0 + updated_at: 1719858965 + username: consumer2 + username_lower: consumer2 + next: null + One consumer: + data: + - created_at: 1719859293 + custom_id: consumer_id3 + id: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + tags: null + type: 0 + updated_at: 1719859293 + username: consumer3 + username_lower: consumer3 + next: null + Multiple consumers: + data: + - created_at: 1719859293 + custom_id: consumer_id3 + id: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + tags: null + type: 0 + updated_at: 1719859293 + username: consumer3 + username_lower: consumer3 + - created_at: 1719858943 + custom_id: consumer_id + id: 73b74f15-5185-4b16-a2fc-3c2fd834ba6c + tags: null + type: 0 + updated_at: 1719858943 + username: consumer + username_lower: consumer + - created_at: 1719858965 + custom_id: consumer_id2 + id: f9383372-7bf4-4275-8bbc-4f89d7a38a23 + tags: null + type: 0 + updated_at: 1719858965 + username: consumer2 + username_lower: consumer2 + next: null + license-response: + description: The license response object. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + created_at: 1500508800 + id: 30b4edb7-0847-4f65-af90-efbed8b0161f + payload: '{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-21","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb","version":"1"}}' + updated_at: 1500508800 + properties: + created_at: + type: integer + example: 1500508800 + id: + type: string + example: 30b4edb7-0847-4f65-af90-efbed8b0161f + description: The UUID of the license + payload: + type: string + example: '{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}' + description: | + The Kong Gateway license in JSON format. + updated_at: + type: integer + example: 1500508800 + examples: + Active license: + value: + created_at: 1500508800 + id: 30b4edb7-0847-4f65-af90-efbed8b0161f + payload: '{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}' + updated_at: 1500508800 + No license: + value: + data: [] + next: null + report-response: + description: Fields available in the report + content: + application/json: + schema: + type: object + x-examples: + Example 1: + counters: + - bucket: 2021-12 + request_count: 0 + db_version: postgres 9.6.19 + kong_version: 3.2.2.1 + license_key: ASDASDASDASDASDASDASDASDASD_ASDASDA + rbac_users: 0 + services_count: 0 + system_info: + cores: 4 + hostname: 13b867agsa008 + uname: Linux x86_64 + workspaces_count: 1 + properties: + counters: + type: array + description: | + Counts the number of requests made in a given month. + items: + type: object + properties: + bucket: + type: string + description: Year and month when the requests were processed. If the value in bucket is UNKNOWN, then the requests were processed before Kong Gateway 2.7.0.1. + example: 2021-12 + request_count: + type: integer + description: Number of requests processed in the given month and year. + example: 0 + db_version: + type: string + description: | + The type and version of the data store Kong Gateway is using. + example: postgres 9.6.19 + kong_version: + type: string + description: | + The version of the Kong Gateway instance. + example: 3.2.2.1 + license_key: + type: string + description: | + An encrypted identifier for the current license key. If no license is present, the field displays as UNLICENSED. + example: ASDASDASDASDASDASDASDASDASD_ASDASDA + rbac_users: + type: integer + description: | + The number of users registered with through RBAC. + example: 0 + services_count: + type: integer + description: | + The number of configured services in the Kong Gateway instance. + example: 0 + system_info: + type: object + description: | + Displays information about the system running Kong Gateway. + properties: + cores: + type: integer + description: Number of CPU cores on the node + example: 11 + hostname: + type: string + description: Encrypted system hostname + example: 13b867agsa008 + uname: + type: string + description: Operating system + example: Linux x86_64 + workspaces_count: + type: integer + description: | + The number of workspaces configured in the Kong Gateway instance. + example: 1 + key-ring-response: + description: The contents of the keyring. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + ids: + - LaW1urRQ + active: LaW1urRQ + description: The keyring object contains an array of keyring ids. + properties: + ids: + type: array + description: The list of the active key IDs + items: + type: string + example: LaW1urRQ + active: + type: string + example: LaW1urRQ + description: The ID of the active key. + examples: + example: + value: + ids: + - LaW1urRQ + active: LaW1urRQ + keyring-generate-response: + description: Keyring response object + content: + application/json: + schema: + type: object + properties: + key: + type: string + id: + type: string + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + workspace-response: + description: The workspace response object. + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + workspace_create_response: + description: The response object for creating a new workspace. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + total: 1 + data: + - created_at: 1529627841000 + id: a43fc3f9-98e4-43b0-b703-c3b1004980d5 + name: default + properties: + total: + type: integer + description: The amount of workspaces. + data: + type: array + description: The array of workspaces + items: + type: object + properties: + created_at: + type: integer + example: 1529627841000 + description: The time and date of workspace creation. + id: + type: string + example: a43fc3f9-98e4-43b0-b703-c3b1004980d5 + description: The unique ID of the workspace + name: + type: string + description: The name assigned in the request body. + example: default + get-endpoints: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: string + x-examples: + Example 1: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /admins + - /admins/password_resets + - /admins/register + - /admins/self/password + - /admins/self/token + - '/admins/{admins}' + - '/admins/{admins}/consumer' + - '/admins/{admins}/rbac_user' + - '/admins/{admin}/roles' + - '/admins/{admin}/workspaces' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumer_groups + - '/consumer_groups/{consumer_groups}' + - '/consumer_groups/{consumer_groups}/consumers' + - '/consumer_groups/{consumer_groups}/consumers/{consumers}' + - '/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - '/consumer_groups/{consumer_groups}/plugins' + - '/consumer_groups/{consumer_groups}/plugins/{plugins}' + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/consumer_groups' + - '/consumers/{consumers}/consumer_groups/{consumer_groups}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /developers + - /developers/export + - /developers/invite + - /developers/roles + - '/developers/roles/{rbac_roles}' + - '/developers/{developers}' + - '/developers/{developers}/applications' + - '/developers/{developers}/applications/{applications}' + - '/developers/{developers}/applications/{applications}/application_instances' + - '/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/consumer' + - '/developers/{developers}/credentials/{plugin}' + - '/developers/{developers}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/rbac_user' + - '/developers/{email_or_id}/plugins/' + - '/developers/{email_or_id}/plugins/{id}' + - /document_objects + - '/document_objects/{document_objects}' + - '/document_objects/{document_objects}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keyring + - /keyring/activate + - /keyring/active + - /keyring/export + - /keyring/generate + - /keyring/import + - /keyring/import/raw + - /keyring/recover + - /keyring/remove + - /keyring/vault/sync + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/consumer_group' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /rbac/roles + - '/rbac/roles/{rbac_roles}' + - '/rbac/roles/{rbac_roles}/endpoints' + - '/rbac/roles/{rbac_roles}/endpoints/permissions' + - '/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - '/rbac/roles/{rbac_roles}/entities' + - '/rbac/roles/{rbac_roles}/entities/permissions' + - '/rbac/roles/{rbac_roles}/entities/{entity_id}' + - '/rbac/roles/{rbac_roles}/permissions' + - /rbac/users + - '/rbac/users/{rbac_users}' + - '/rbac/users/{rbac_users}/admins' + - '/rbac/users/{rbac_users}/admins/{admins}' + - '/rbac/users/{rbac_users}/developers' + - '/rbac/users/{rbac_users}/developers/{developers}' + - '/rbac/users/{rbac_users}/permissions' + - '/rbac/users/{rbac_users}/roles' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/document_objects' + - '/services/{services}/document_objects/{document_objects}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + - /workspaces + - '/workspaces/{workspaces}' + - '/workspaces/{workspaces}/meta' + - '/{workspace_name}/kong' + - workspace_/acls + - 'workspace_/acls/{acls}' + - 'workspace_/acls/{acls}/consumer' + - workspace_/acme + - workspace_/acme/certificates + - 'workspace_/acme/certificates/{certificates}' + - workspace_/acme_storage + - 'workspace_/acme_storage/{acme_storage}' + - workspace_/admins + - workspace_/admins/password_resets + - workspace_/admins/register + - workspace_/admins/self/password + - workspace_/admins/self/token + - 'workspace_/admins/{admins}' + - 'workspace_/admins/{admins}/consumer' + - 'workspace_/admins/{admins}/rbac_user' + - 'workspace_/admins/{admin}/roles' + - 'workspace_/admins/{admin}/workspaces' + - workspace_/applications + - 'workspace_/applications/{applications}' + - 'workspace_/applications/{applications}/application_instances' + - 'workspace_/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/applications/{applications}/consumer' + - 'workspace_/applications/{applications}/credentials/{plugin}' + - 'workspace_/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/applications/{applications}/developer' + - workspace_/auth + - workspace_/basic-auths + - 'workspace_/basic-auths/{basicauth_credentials}' + - 'workspace_/basic-auths/{basicauth_credentials}/consumer' + - workspace_/ca_certificates + - 'workspace_/ca_certificates/{ca_certificates}' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - workspace_/cache + - 'workspace_/cache/{key}' + - workspace_/certificates + - 'workspace_/certificates/{certificates}' + - 'workspace_/certificates/{certificates}/services' + - 'workspace_/certificates/{certificates}/services/{services}' + - 'workspace_/certificates/{certificates}/snis' + - 'workspace_/certificates/{certificates}/snis/{snis}' + - 'workspace_/certificates/{certificates}/upstreams' + - 'workspace_/certificates/{certificates}/upstreams/{upstreams}' + - workspace_/clustering/data-planes + - workspace_/clustering/status + - workspace_/config + - workspace_/consumer_groups + - 'workspace_/consumer_groups/{consumer_groups}' + - 'workspace_/consumer_groups/{consumer_groups}/consumers' + - 'workspace_/consumer_groups/{consumer_groups}/consumers/{consumers}' + - 'workspace_/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - 'workspace_/consumer_groups/{consumer_groups}/plugins' + - 'workspace_/consumer_groups/{consumer_groups}/plugins/{plugins}' + - workspace_/consumers + - 'workspace_/consumers/{consumers}' + - 'workspace_/consumers/{consumers}/acls' + - 'workspace_/consumers/{consumers}/acls/{acls}' + - 'workspace_/consumers/{consumers}/admins' + - 'workspace_/consumers/{consumers}/admins/{admins}' + - 'workspace_/consumers/{consumers}/applications' + - 'workspace_/consumers/{consumers}/applications/{applications}' + - 'workspace_/consumers/{consumers}/basic-auth' + - 'workspace_/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - 'workspace_/consumers/{consumers}/consumer_groups' + - 'workspace_/consumers/{consumers}/consumer_groups/{consumer_groups}' + - 'workspace_/consumers/{consumers}/developers' + - 'workspace_/consumers/{consumers}/developers/{developers}' + - 'workspace_/consumers/{consumers}/hmac-auth' + - 'workspace_/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - 'workspace_/consumers/{consumers}/jwt' + - 'workspace_/consumers/{consumers}/jwt/{jwt_secrets}' + - 'workspace_/consumers/{consumers}/key-auth' + - 'workspace_/consumers/{consumers}/key-auth/{keyauth_credentials}' + - 'workspace_/consumers/{consumers}/key-auth-enc' + - 'workspace_/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - 'workspace_/consumers/{consumers}/login_attempts' + - 'workspace_/consumers/{consumers}/login_attempts/{login_attempts}' + - 'workspace_/consumers/{consumers}/mtls-auth' + - 'workspace_/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/oauth2' + - 'workspace_/consumers/{consumers}/oauth2/{oauth2_credentials}' + - 'workspace_/consumers/{consumers}/plugins' + - 'workspace_/consumers/{consumers}/plugins/{plugins}' + - 'workspace_/debug/cluster/log-level/{log_level}' + - workspace_/debug/node/log-level + - 'workspace_/debug/node/log-level/{log_level}' + - workspace_/debug/profiling/cpu + - workspace_/debug/profiling/gc-snapshot + - workspace_/debug/profiling/memory + - workspace_/degraphql_routes + - 'workspace_/degraphql_routes/{degraphql_routes}' + - 'workspace_/degraphql_routes/{degraphql_routes}/service' + - workspace_/developers + - workspace_/developers/export + - workspace_/developers/invite + - workspace_/developers/roles + - 'workspace_/developers/roles/{rbac_roles}' + - 'workspace_/developers/{developers}' + - 'workspace_/developers/{developers}/applications' + - 'workspace_/developers/{developers}/applications/{applications}' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/consumer' + - 'workspace_/developers/{developers}/credentials/{plugin}' + - 'workspace_/developers/{developers}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/rbac_user' + - 'workspace_/developers/{email_or_id}/plugins/' + - 'workspace_/developers/{email_or_id}/plugins/{id}' + - workspace_/document_objects + - 'workspace_/document_objects/{document_objects}' + - 'workspace_/document_objects/{document_objects}/service' + - workspace_/endpoints + - workspace_/entities/migrate + - workspace_/event-hooks + - workspace_/event-hooks/sources + - 'workspace_/event-hooks/sources/{source}' + - 'workspace_/event-hooks/sources/{source}/{event}' + - 'workspace_/event-hooks/{event_hooks}' + - 'workspace_/event-hooks/{event_hooks}/ping' + - 'workspace_/event-hooks/{event_hooks}/test' + - workspace_/files + - workspace_/files/* + - workspace_/files/partials/* + - 'workspace_/files/{files}' + - workspace_/filter-chains + - 'workspace_/filter-chains/{filter_chains}' + - 'workspace_/filter-chains/{filter_chains}/route' + - 'workspace_/filter-chains/{filter_chains}/service' + - workspace_/graphql-proxy-cache-advanced + - 'workspace_/graphql-proxy-cache-advanced/{cache_key}' + - 'workspace_/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/graphql-rate-limiting-advanced/costs + - 'workspace_/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - workspace_/graphql_ratelimiting_advanced_cost_decoration + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - workspace_/groups + - 'workspace_/groups/{groups}' + - 'workspace_/groups/{groups}/roles' + - workspace_/hmac-auths + - 'workspace_/hmac-auths/{hmacauth_credentials}' + - 'workspace_/hmac-auths/{hmacauth_credentials}/consumer' + - workspace_/jwt-signer/jwks + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}' + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - workspace_/jwts + - 'workspace_/jwts/{jwt_secrets}' + - 'workspace_/jwts/{jwt_secrets}/consumer' + - workspace_/key-auths + - 'workspace_/key-auths/{keyauth_credentials}' + - 'workspace_/key-auths/{keyauth_credentials}/consumer' + - workspace_/key-auths-enc + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}' + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}/consumer' + - workspace_/key-sets + - 'workspace_/key-sets/{key_sets}' + - 'workspace_/key-sets/{key_sets}/keys' + - 'workspace_/key-sets/{key_sets}/keys/{keys}' + - workspace_/keyring + - workspace_/keyring/activate + - workspace_/keyring/active + - workspace_/keyring/export + - workspace_/keyring/generate + - workspace_/keyring/import + - workspace_/keyring/import/raw + - workspace_/keyring/recover + - workspace_/keyring/remove + - workspace_/keyring/vault/sync + - workspace_/keys + - 'workspace_/keys/{keys}' + - 'workspace_/keys/{keys}/set' + - workspace_/konnect_applications + - 'workspace_/konnect_applications/{konnect_applications}' + - workspace_/license/report + - workspace_/licenses + - 'workspace_/licenses/{licenses}' + - workspace_/login_attempts + - 'workspace_/login_attempts/{login_attempts}' + - 'workspace_/login_attempts/{login_attempts}/consumer' + - workspace_/metrics + - workspace_/mtls-auths + - 'workspace_/mtls-auths/{mtls_auth_credentials}/consumer' + - workspace_/mtls_auth_credentials + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - workspace_/oauth2 + - 'workspace_/oauth2/{oauth2_credentials}' + - 'workspace_/oauth2/{oauth2_credentials}/consumer' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - workspace_/oauth2_tokens + - 'workspace_/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/credential' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/service' + - workspace_/openid-connect/issuers + - 'workspace_/openid-connect/issuers/{oic_issuers}' + - workspace_/openid-connect/jwks + - workspace_/plugins + - workspace_/plugins/enabled + - 'workspace_/plugins/schema/{name}' + - 'workspace_/plugins/{plugins}' + - 'workspace_/plugins/{plugins}/consumer' + - 'workspace_/plugins/{plugins}/consumer_group' + - 'workspace_/plugins/{plugins}/route' + - 'workspace_/plugins/{plugins}/service' + - workspace_/proxy-cache + - 'workspace_/proxy-cache/{cache_key}' + - 'workspace_/proxy-cache/{plugin_id}/caches/{cache_key}' + - workspace_/proxy-cache-advanced + - 'workspace_/proxy-cache-advanced/{cache_key}' + - 'workspace_/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/rbac/roles + - 'workspace_/rbac/roles/{rbac_roles}' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - 'workspace_/rbac/roles/{rbac_roles}/entities' + - 'workspace_/rbac/roles/{rbac_roles}/entities/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/entities/{entity_id}' + - 'workspace_/rbac/roles/{rbac_roles}/permissions' + - workspace_/rbac/users + - 'workspace_/rbac/users/{rbac_users}' + - 'workspace_/rbac/users/{rbac_users}/admins' + - 'workspace_/rbac/users/{rbac_users}/admins/{admins}' + - 'workspace_/rbac/users/{rbac_users}/developers' + - 'workspace_/rbac/users/{rbac_users}/developers/{developers}' + - 'workspace_/rbac/users/{rbac_users}/permissions' + - 'workspace_/rbac/users/{rbac_users}/roles' + - workspace_/routes + - 'workspace_/routes/{routes}' + - 'workspace_/routes/{routes}/filter-chains' + - 'workspace_/routes/{routes}/filter-chains/{filter_chains}' + - 'workspace_/routes/{routes}/filters/all' + - 'workspace_/routes/{routes}/filters/disabled' + - 'workspace_/routes/{routes}/filters/enabled' + - 'workspace_/routes/{routes}/plugins' + - 'workspace_/routes/{routes}/plugins/{plugins}' + - 'workspace_/routes/{routes}/service' + - workspace_/schemas/plugins/validate + - 'workspace_/schemas/plugins/{name}' + - 'workspace_/schemas/{db_entity_name}/validate' + - 'workspace_/schemas/{name}' + - workspace_/services + - 'workspace_/services/{services}' + - 'workspace_/services/{services}/application_instances' + - 'workspace_/services/{services}/application_instances/{application_instances}' + - 'workspace_/services/{services}/applications' + - 'workspace_/services/{services}/client_certificate' + - 'workspace_/services/{services}/degraphql/routes' + - 'workspace_/services/{services}/degraphql/routes/{degraphql_routes}' + - 'workspace_/services/{services}/degraphql_routes' + - 'workspace_/services/{services}/degraphql_routes/{degraphql_routes}' + - 'workspace_/services/{services}/document_objects' + - 'workspace_/services/{services}/document_objects/{document_objects}' + - 'workspace_/services/{services}/filter-chains' + - 'workspace_/services/{services}/filter-chains/{filter_chains}' + - 'workspace_/services/{services}/graphql-rate-limiting-advanced/costs' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/services/{services}/oauth2_tokens' + - 'workspace_/services/{services}/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/services/{services}/plugins' + - 'workspace_/services/{services}/plugins/{plugins}' + - 'workspace_/services/{services}/routes' + - 'workspace_/services/{services}/routes/{routes}' + - workspace_/sessions + - 'workspace_/sessions/{sessions}' + - workspace_/snis + - 'workspace_/snis/{snis}' + - 'workspace_/snis/{snis}/certificate' + - workspace_/status + - workspace_/tags + - 'workspace_/tags/{tags}' + - workspace_/targets + - 'workspace_/targets/{targets}' + - 'workspace_/targets/{targets}/upstream' + - workspace_/timers + - workspace_/upstreams + - 'workspace_/upstreams/{upstreams}' + - 'workspace_/upstreams/{upstreams}/client_certificate' + - 'workspace_/upstreams/{upstreams}/health' + - 'workspace_/upstreams/{upstreams}/targets' + - 'workspace_/upstreams/{upstreams}/targets/all' + - 'workspace_/upstreams/{upstreams}/targets/{targets}' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/unhealthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - workspace_/userinfo + - workspace_/vault-auth + - 'workspace_/vault-auth/{vault_auth_vaults}' + - 'workspace_/vault-auth/{vault}/credentials' + - 'workspace_/vault-auth/{vault}/credentials/token/{access_token}' + - 'workspace_/vault-auth/{vault}/credentials/{consumer}' + - workspace_/vaults + - 'workspace_/vaults/{vaults}' + - workspace_/vitals/ + - workspace_/vitals/cluster + - workspace_/vitals/cluster/status_codes + - 'workspace_/vitals/consumers/{consumer_id}/cluster' + - workspace_/vitals/nodes/ + - 'workspace_/vitals/nodes/{node_id}' + - 'workspace_/vitals/reports/{entity_type}' + - workspace_/vitals/status_code_classes + - workspace_/vitals/status_codes/by_consumer + - workspace_/vitals/status_codes/by_consumer_and_route + - workspace_/vitals/status_codes/by_route + - workspace_/vitals/status_codes/by_service + - workspace_/workspaces + - 'workspace_/workspaces/{workspaces}' + - 'workspace_/workspaces/{workspaces}/meta' + examples: + Get all endpoints: + value: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /admins + - /admins/password_resets + - /admins/register + - /admins/self/password + - /admins/self/token + - '/admins/{admins}' + - '/admins/{admins}/consumer' + - '/admins/{admins}/rbac_user' + - '/admins/{admin}/roles' + - '/admins/{admin}/workspaces' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumer_groups + - '/consumer_groups/{consumer_groups}' + - '/consumer_groups/{consumer_groups}/consumers' + - '/consumer_groups/{consumer_groups}/consumers/{consumers}' + - '/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - '/consumer_groups/{consumer_groups}/plugins' + - '/consumer_groups/{consumer_groups}/plugins/{plugins}' + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/consumer_groups' + - '/consumers/{consumers}/consumer_groups/{consumer_groups}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /developers + - /developers/export + - /developers/invite + - /developers/roles + - '/developers/roles/{rbac_roles}' + - '/developers/{developers}' + - '/developers/{developers}/applications' + - '/developers/{developers}/applications/{applications}' + - '/developers/{developers}/applications/{applications}/application_instances' + - '/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/consumer' + - '/developers/{developers}/credentials/{plugin}' + - '/developers/{developers}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/rbac_user' + - '/developers/{email_or_id}/plugins/' + - '/developers/{email_or_id}/plugins/{id}' + - /document_objects + - '/document_objects/{document_objects}' + - '/document_objects/{document_objects}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keyring + - /keyring/activate + - /keyring/active + - /keyring/export + - /keyring/generate + - /keyring/import + - /keyring/import/raw + - /keyring/recover + - /keyring/remove + - /keyring/vault/sync + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/consumer_group' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /rbac/roles + - '/rbac/roles/{rbac_roles}' + - '/rbac/roles/{rbac_roles}/endpoints' + - '/rbac/roles/{rbac_roles}/endpoints/permissions' + - '/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - '/rbac/roles/{rbac_roles}/entities' + - '/rbac/roles/{rbac_roles}/entities/permissions' + - '/rbac/roles/{rbac_roles}/entities/{entity_id}' + - '/rbac/roles/{rbac_roles}/permissions' + - /rbac/users + - '/rbac/users/{rbac_users}' + - '/rbac/users/{rbac_users}/admins' + - '/rbac/users/{rbac_users}/admins/{admins}' + - '/rbac/users/{rbac_users}/developers' + - '/rbac/users/{rbac_users}/developers/{developers}' + - '/rbac/users/{rbac_users}/permissions' + - '/rbac/users/{rbac_users}/roles' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/document_objects' + - '/services/{services}/document_objects/{document_objects}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + - /workspaces + - '/workspaces/{workspaces}' + - '/workspaces/{workspaces}/meta' + - '/{workspace_name}/kong' + - workspace_/acls + - 'workspace_/acls/{acls}' + - 'workspace_/acls/{acls}/consumer' + - workspace_/acme + - workspace_/acme/certificates + - 'workspace_/acme/certificates/{certificates}' + - workspace_/acme_storage + - 'workspace_/acme_storage/{acme_storage}' + - workspace_/admins + - workspace_/admins/password_resets + - workspace_/admins/register + - workspace_/admins/self/password + - workspace_/admins/self/token + - 'workspace_/admins/{admins}' + - 'workspace_/admins/{admins}/consumer' + - 'workspace_/admins/{admins}/rbac_user' + - 'workspace_/admins/{admin}/roles' + - 'workspace_/admins/{admin}/workspaces' + - workspace_/applications + - 'workspace_/applications/{applications}' + - 'workspace_/applications/{applications}/application_instances' + - 'workspace_/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/applications/{applications}/consumer' + - 'workspace_/applications/{applications}/credentials/{plugin}' + - 'workspace_/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/applications/{applications}/developer' + - workspace_/auth + - workspace_/basic-auths + - 'workspace_/basic-auths/{basicauth_credentials}' + - 'workspace_/basic-auths/{basicauth_credentials}/consumer' + - workspace_/ca_certificates + - 'workspace_/ca_certificates/{ca_certificates}' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - workspace_/cache + - 'workspace_/cache/{key}' + - workspace_/certificates + - 'workspace_/certificates/{certificates}' + - 'workspace_/certificates/{certificates}/services' + - 'workspace_/certificates/{certificates}/services/{services}' + - 'workspace_/certificates/{certificates}/snis' + - 'workspace_/certificates/{certificates}/snis/{snis}' + - 'workspace_/certificates/{certificates}/upstreams' + - 'workspace_/certificates/{certificates}/upstreams/{upstreams}' + - workspace_/clustering/data-planes + - workspace_/clustering/status + - workspace_/config + - workspace_/consumer_groups + - 'workspace_/consumer_groups/{consumer_groups}' + - 'workspace_/consumer_groups/{consumer_groups}/consumers' + - 'workspace_/consumer_groups/{consumer_groups}/consumers/{consumers}' + - 'workspace_/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - 'workspace_/consumer_groups/{consumer_groups}/plugins' + - 'workspace_/consumer_groups/{consumer_groups}/plugins/{plugins}' + - workspace_/consumers + - 'workspace_/consumers/{consumers}' + - 'workspace_/consumers/{consumers}/acls' + - 'workspace_/consumers/{consumers}/acls/{acls}' + - 'workspace_/consumers/{consumers}/admins' + - 'workspace_/consumers/{consumers}/admins/{admins}' + - 'workspace_/consumers/{consumers}/applications' + - 'workspace_/consumers/{consumers}/applications/{applications}' + - 'workspace_/consumers/{consumers}/basic-auth' + - 'workspace_/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - 'workspace_/consumers/{consumers}/consumer_groups' + - 'workspace_/consumers/{consumers}/consumer_groups/{consumer_groups}' + - 'workspace_/consumers/{consumers}/developers' + - 'workspace_/consumers/{consumers}/developers/{developers}' + - 'workspace_/consumers/{consumers}/hmac-auth' + - 'workspace_/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - 'workspace_/consumers/{consumers}/jwt' + - 'workspace_/consumers/{consumers}/jwt/{jwt_secrets}' + - 'workspace_/consumers/{consumers}/key-auth' + - 'workspace_/consumers/{consumers}/key-auth/{keyauth_credentials}' + - 'workspace_/consumers/{consumers}/key-auth-enc' + - 'workspace_/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - 'workspace_/consumers/{consumers}/login_attempts' + - 'workspace_/consumers/{consumers}/login_attempts/{login_attempts}' + - 'workspace_/consumers/{consumers}/mtls-auth' + - 'workspace_/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/oauth2' + - 'workspace_/consumers/{consumers}/oauth2/{oauth2_credentials}' + - 'workspace_/consumers/{consumers}/plugins' + - 'workspace_/consumers/{consumers}/plugins/{plugins}' + - 'workspace_/debug/cluster/log-level/{log_level}' + - workspace_/debug/node/log-level + - 'workspace_/debug/node/log-level/{log_level}' + - workspace_/debug/profiling/cpu + - workspace_/debug/profiling/gc-snapshot + - workspace_/debug/profiling/memory + - workspace_/degraphql_routes + - 'workspace_/degraphql_routes/{degraphql_routes}' + - 'workspace_/degraphql_routes/{degraphql_routes}/service' + - workspace_/developers + - workspace_/developers/export + - workspace_/developers/invite + - workspace_/developers/roles + - 'workspace_/developers/roles/{rbac_roles}' + - 'workspace_/developers/{developers}' + - 'workspace_/developers/{developers}/applications' + - 'workspace_/developers/{developers}/applications/{applications}' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/consumer' + - 'workspace_/developers/{developers}/credentials/{plugin}' + - 'workspace_/developers/{developers}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/rbac_user' + - 'workspace_/developers/{email_or_id}/plugins/' + - 'workspace_/developers/{email_or_id}/plugins/{id}' + - workspace_/document_objects + - 'workspace_/document_objects/{document_objects}' + - 'workspace_/document_objects/{document_objects}/service' + - workspace_/endpoints + - workspace_/entities/migrate + - workspace_/event-hooks + - workspace_/event-hooks/sources + - 'workspace_/event-hooks/sources/{source}' + - 'workspace_/event-hooks/sources/{source}/{event}' + - 'workspace_/event-hooks/{event_hooks}' + - 'workspace_/event-hooks/{event_hooks}/ping' + - 'workspace_/event-hooks/{event_hooks}/test' + - workspace_/files + - workspace_/files/* + - workspace_/files/partials/* + - 'workspace_/files/{files}' + - workspace_/filter-chains + - 'workspace_/filter-chains/{filter_chains}' + - 'workspace_/filter-chains/{filter_chains}/route' + - 'workspace_/filter-chains/{filter_chains}/service' + - workspace_/graphql-proxy-cache-advanced + - 'workspace_/graphql-proxy-cache-advanced/{cache_key}' + - 'workspace_/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/graphql-rate-limiting-advanced/costs + - 'workspace_/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - workspace_/graphql_ratelimiting_advanced_cost_decoration + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - workspace_/groups + - 'workspace_/groups/{groups}' + - 'workspace_/groups/{groups}/roles' + - workspace_/hmac-auths + - 'workspace_/hmac-auths/{hmacauth_credentials}' + - 'workspace_/hmac-auths/{hmacauth_credentials}/consumer' + - workspace_/jwt-signer/jwks + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}' + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - workspace_/jwts + - 'workspace_/jwts/{jwt_secrets}' + - 'workspace_/jwts/{jwt_secrets}/consumer' + - workspace_/key-auths + - 'workspace_/key-auths/{keyauth_credentials}' + - 'workspace_/key-auths/{keyauth_credentials}/consumer' + - workspace_/key-auths-enc + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}' + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}/consumer' + - workspace_/key-sets + - 'workspace_/key-sets/{key_sets}' + - 'workspace_/key-sets/{key_sets}/keys' + - 'workspace_/key-sets/{key_sets}/keys/{keys}' + - workspace_/keyring + - workspace_/keyring/activate + - workspace_/keyring/active + - workspace_/keyring/export + - workspace_/keyring/generate + - workspace_/keyring/import + - workspace_/keyring/import/raw + - workspace_/keyring/recover + - workspace_/keyring/remove + - workspace_/keyring/vault/sync + - workspace_/keys + - 'workspace_/keys/{keys}' + - 'workspace_/keys/{keys}/set' + - workspace_/konnect_applications + - 'workspace_/konnect_applications/{konnect_applications}' + - workspace_/license/report + - workspace_/licenses + - 'workspace_/licenses/{licenses}' + - workspace_/login_attempts + - 'workspace_/login_attempts/{login_attempts}' + - 'workspace_/login_attempts/{login_attempts}/consumer' + - workspace_/metrics + - workspace_/mtls-auths + - 'workspace_/mtls-auths/{mtls_auth_credentials}/consumer' + - workspace_/mtls_auth_credentials + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - workspace_/oauth2 + - 'workspace_/oauth2/{oauth2_credentials}' + - 'workspace_/oauth2/{oauth2_credentials}/consumer' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - workspace_/oauth2_tokens + - 'workspace_/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/credential' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/service' + - workspace_/openid-connect/issuers + - 'workspace_/openid-connect/issuers/{oic_issuers}' + - workspace_/openid-connect/jwks + - workspace_/plugins + - workspace_/plugins/enabled + - 'workspace_/plugins/schema/{name}' + - 'workspace_/plugins/{plugins}' + - 'workspace_/plugins/{plugins}/consumer' + - 'workspace_/plugins/{plugins}/consumer_group' + - 'workspace_/plugins/{plugins}/route' + - 'workspace_/plugins/{plugins}/service' + - workspace_/proxy-cache + - 'workspace_/proxy-cache/{cache_key}' + - 'workspace_/proxy-cache/{plugin_id}/caches/{cache_key}' + - workspace_/proxy-cache-advanced + - 'workspace_/proxy-cache-advanced/{cache_key}' + - 'workspace_/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/rbac/roles + - 'workspace_/rbac/roles/{rbac_roles}' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - 'workspace_/rbac/roles/{rbac_roles}/entities' + - 'workspace_/rbac/roles/{rbac_roles}/entities/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/entities/{entity_id}' + - 'workspace_/rbac/roles/{rbac_roles}/permissions' + - workspace_/rbac/users + - 'workspace_/rbac/users/{rbac_users}' + - 'workspace_/rbac/users/{rbac_users}/admins' + - 'workspace_/rbac/users/{rbac_users}/admins/{admins}' + - 'workspace_/rbac/users/{rbac_users}/developers' + - 'workspace_/rbac/users/{rbac_users}/developers/{developers}' + - 'workspace_/rbac/users/{rbac_users}/permissions' + - 'workspace_/rbac/users/{rbac_users}/roles' + - workspace_/routes + - 'workspace_/routes/{routes}' + - 'workspace_/routes/{routes}/filter-chains' + - 'workspace_/routes/{routes}/filter-chains/{filter_chains}' + - 'workspace_/routes/{routes}/filters/all' + - 'workspace_/routes/{routes}/filters/disabled' + - 'workspace_/routes/{routes}/filters/enabled' + - 'workspace_/routes/{routes}/plugins' + - 'workspace_/routes/{routes}/plugins/{plugins}' + - 'workspace_/routes/{routes}/service' + - workspace_/schemas/plugins/validate + - 'workspace_/schemas/plugins/{name}' + - 'workspace_/schemas/{db_entity_name}/validate' + - 'workspace_/schemas/{name}' + - workspace_/services + - 'workspace_/services/{services}' + - 'workspace_/services/{services}/application_instances' + - 'workspace_/services/{services}/application_instances/{application_instances}' + - 'workspace_/services/{services}/applications' + - 'workspace_/services/{services}/client_certificate' + - 'workspace_/services/{services}/degraphql/routes' + - 'workspace_/services/{services}/degraphql/routes/{degraphql_routes}' + - 'workspace_/services/{services}/degraphql_routes' + - 'workspace_/services/{services}/degraphql_routes/{degraphql_routes}' + - 'workspace_/services/{services}/document_objects' + - 'workspace_/services/{services}/document_objects/{document_objects}' + - 'workspace_/services/{services}/filter-chains' + - 'workspace_/services/{services}/filter-chains/{filter_chains}' + - 'workspace_/services/{services}/graphql-rate-limiting-advanced/costs' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/services/{services}/oauth2_tokens' + - 'workspace_/services/{services}/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/services/{services}/plugins' + - 'workspace_/services/{services}/plugins/{plugins}' + - 'workspace_/services/{services}/routes' + - 'workspace_/services/{services}/routes/{routes}' + - workspace_/sessions + - 'workspace_/sessions/{sessions}' + - workspace_/snis + - 'workspace_/snis/{snis}' + - 'workspace_/snis/{snis}/certificate' + - workspace_/status + - workspace_/tags + - 'workspace_/tags/{tags}' + - workspace_/targets + - 'workspace_/targets/{targets}' + - 'workspace_/targets/{targets}/upstream' + - workspace_/timers + - workspace_/upstreams + - 'workspace_/upstreams/{upstreams}' + - 'workspace_/upstreams/{upstreams}/client_certificate' + - 'workspace_/upstreams/{upstreams}/health' + - 'workspace_/upstreams/{upstreams}/targets' + - 'workspace_/upstreams/{upstreams}/targets/all' + - 'workspace_/upstreams/{upstreams}/targets/{targets}' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/unhealthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - workspace_/userinfo + - workspace_/vault-auth + - 'workspace_/vault-auth/{vault_auth_vaults}' + - 'workspace_/vault-auth/{vault}/credentials' + - 'workspace_/vault-auth/{vault}/credentials/token/{access_token}' + - 'workspace_/vault-auth/{vault}/credentials/{consumer}' + - workspace_/vaults + - 'workspace_/vaults/{vaults}' + - workspace_/vitals/ + - workspace_/vitals/cluster + - workspace_/vitals/cluster/status_codes + - 'workspace_/vitals/consumers/{consumer_id}/cluster' + - workspace_/vitals/nodes/ + - 'workspace_/vitals/nodes/{node_id}' + - 'workspace_/vitals/reports/{entity_type}' + - workspace_/vitals/status_code_classes + - workspace_/vitals/status_codes/by_consumer + - workspace_/vitals/status_codes/by_consumer_and_route + - workspace_/vitals/status_codes/by_route + - workspace_/vitals/status_codes/by_service + - workspace_/workspaces + - 'workspace_/workspaces/{workspaces}' + - 'workspace_/workspaces/{workspaces}/meta' + admins-response: + description: Example response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + status: 4 + username: test-admin + email: test@test.com + rbac_token_enabled: true + - created_at: 1556563122 + id: a93ff120-9e6c-4198-b47e-f779104c7eac + updated_at: 1556563122 + status: 0 + username: kong_admin + rbac_token_enabled: false + next: null + properties: + data: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + status: + type: integer + description: The status field indicates the state of the invitation. + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + next: + nullable: true + groups-response: + description: Example response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - created_at: 1717123483 + id: 4844ded2-06d1-44f5-974a-03982696f889 + updated_at: 1717123483 + name: group1 + comment: comment1 + - created_at: 1717123637 + id: 65b3d436-3c5b-4b0e-a2a5-ee188d526ad8 + updated_at: 1717123637 + name: group2 + comment: comment2 + next: null + properties: + data: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + name: + type: string + comment: + type: string + next: + nullable: true + rbac-user-response: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + enabled: + type: boolean + id: + type: string + name: + type: string + user_token: + type: string + user_token_ident: + type: string + next: + type: string + x-examples: + Example 1: + data: + - comment: null + created_at: 1557512629 + enabled: true + id: f035f120-a95e-4327-b2ae-8fa264601d75 + name: doc_lord + user_token: $2b$09$TIMneYcTosdG9WbzRsqcweAS2zote8g6I8HqXAtbFHR1pds2ymsh6 + user_token_ident: 88ea3 + - comment: null + created_at: 1557522650 + enabled: true + id: fa6881b2-f49f-4007-9475-577cd21d34f4 + name: doc_knight + user_token: $2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG + user_token_ident: 4d870 + next: null + examples: + Returned user: + value: + data: + - comment: null + created_at: 1557512629 + enabled: true + id: f035f120-a95e-4327-b2ae-8fa264601d75 + name: doc_lord + user_token: $2b$09$TIMneYcTosdG9WbzRsqcweAS2zote8g6I8HqXAtbFHR1pds2ymsh6 + user_token_ident: 88ea3 + - comment: null + created_at: 1557522650 + enabled: true + id: fa6881b2-f49f-4007-9475-577cd21d34f4 + name: doc_knight + user_token: $2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG + user_token_ident: 4d870 + next: null + audit-objects-response: + description: Example response generated for checking the `/status` endpoint without RBAC enabled. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - client_ip: 127.0.0.1 + method: GET + path: /status + payload: null + rbac_user_id: null + rbac_user_name: null + removed_from_payload: null + request_id: OjOcUBvt6q6XJlX3dd6BSpy1uUkTyctC + request_source: null + request_timestamp: 1676424547 + signature: null + status: 200 + ttl: 2591997 + workspace: 1065b6d6-219f-4002-b3e9-334fc3eff46c + total: 1 + properties: + data: + type: array + description: The client IP address + items: + type: object + properties: + client_ip: + type: string + description: The client IP address + method: + type: string + description: The HTTP method + path: + type: string + description: The path of the endpoint + payload: + nullable: true + rbac_user_id: + nullable: true + rbac_user_name: + nullable: true + removed_from_payload: + nullable: true + request_id: + type: string + request_source: + nullable: true + request_timestamp: + type: integer + signature: + nullable: true + status: + type: integer + ttl: + type: integer + workspace: + type: string + total: + type: integer + database-audit-log-response: + description: Example response for a consumer creation log entry + content: + application/json: + schema: + properties: + id: + type: string + event-hooks-response: + description: Example event hooks response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + config: + type: object + properties: + body: + type: string + body_format: + type: boolean + headers: + type: object + properties: + content-type: + type: string + headers_format: + type: boolean + method: + type: string + payload: + type: object + properties: + text: + type: string + payload_format: + type: boolean + secret: + type: string + ssl_verify: + type: boolean + url: + type: string + functions: + type: array + items: + type: string + created_at: + type: integer + event: + type: string + handler: + type: string + id: + type: string + on_change: + type: string + snooze: + type: integer + source: + type: string + next: + type: string + x-examples: + Example 1: + data: + - config: + body: null + body_format: true + headers: + content-type: application/json + headers_format: false + method: POST + payload: + text: payload_text + payload_format: true + secret: null + ssl_verify: false + url: 'https://hooks.slack.com/services/foo/bar/baz' + created_at: 1627588552 + event: admins + handler: webhook-custom + id: 937df175-3db2-4e6d-8aa1-d95c94a76089 + on_change: null + snooze: null + source: crud + - config: + headers: {} + secret: null + ssl_verify: false + url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + created_at: 1627581575 + event: consumers + handler: webhook + id: c57340ab-9fed-40fd-bb7e-1cef8d37c2df + on_change: null + snooze: null + source: crud + - config: + functions: + - | + return function (data, event, source, pid) + local user = data.entity.username + error("Event hook on consumer " .. user .. "") + end + created_at: 1627595513 + event: consumers + handler: lambda + id: c9fdd58d-5416-4d3a-9467-51e5cfe4ca0e + on_change: null + snooze: null + source: crud + next: null + examples: + Example event hooks response: + value: + data: + - config: + body: "null" + body_format: true + headers: + content-type: string + headers_format: true + method: string + payload: + text: string + payload_format: true + secret: "null" + ssl_verify: true + url: string + functions: + - string + created_at: 0 + event: string + handler: string + id: string + on_change: "string" + snooze: 0 + source: string + next: "null" + event-hooks-request: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + event: + description: A string describing the Kong entity the event hook listens to for events. + type: object + properties: + type: + type: string + description: + type: string + handler: + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + type: object + properties: + type: + type: string + description: + type: string + source: + type: object + description: A string describing the action that triggers the event hook. + properties: + type: + type: string + description: + type: string + snooze: + type: object + description: An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + properties: + type: + type: string + description: + type: string + on_change: + type: object + description: An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + properties: + type: + type: string + description: + type: string + config.url: + type: object + description: The URL the JSON POST request is made to with the event data as the payload. + properties: + type: + type: string + description: + type: string + config.method: + type: object + description: The HTTP method used to create the custom webhook. + properties: + type: + type: string + description: + type: string + config.payload: + type: object + description: An object that includes key/value pairs that describe the configurable payload body. Supports templating. The full list of available template parameters can be found in the `/sources` API output, under the `fields` JSON object. + properties: + type: + type: string + description: + type: string + config.payload_format: + type: object + properties: + type: + type: string + description: A optional boolean (defaults to true) indicating whether to format the `config.payload` with resty templating. When set to false, the payload is sent as a raw object. + description: + type: string + config.body: + type: object + properties: + type: + type: string + description: + type: string + config.body_format: + type: object + properties: + type: + type: string + description: + type: string + config.headers: + type: object + properties: + type: + type: string + description: + type: string + config.headers_format: + type: object + properties: + type: + type: string + description: + type: string + config.secret: + type: object + properties: + type: + type: string + description: + type: string + config.ssl_verify: + type: object + properties: + type: + type: string + description: + type: string + x-examples: + Example 1: + data: + event: + type: string + description: A string describing the Kong entity the event hook listens to for events. (optional) + handler: + type: string + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. (required) + source: + type: string + description: A string describing the action that triggers the event 'https://hooks.slack.com/services/foo/bar/baz' + requried: true + snooze: + type: integer + description: An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + on_change: + type: boolean + description: An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + config.url: + type: string + description: The URL the JSON POST request is made to with the event data as the payloads. + required: true + config.method: + type: string + description: The HTTP method used to create the custom webhook. + required: true + config.payload: + type: object + description: An object that includes key/value pairs that describe the configurable payload body. Supports templating. + config.payload_format: + type: boolean + description: An optional boolean indicating whether to format the config.payload with resty templating. When set to false, the payload is sent as a raw object. + default: true + config.body: + type: string + description: An optional string sent in the remote request. + config.body_format: + type: boolean + description: An optional boolean indicating whether to format `config.body` with resty templating. When set to false, the body is sent as a raw object. + default: true + config.headers: + type: object + description: An object defining additional HTTP headers to send in the webhook request. + config.headers_format: + type: boolean + description: An optional boolean indicating whether to format `config.headers` with resty templating. When set to true, the `config.headers` value is treated as a template. + default: false + config.secret: + type: string + description: An optional string used to sign the remote webhook for remote verification. When set, Kong signs the body of the event hook with HMAC-SHA1 and includes it in a header, `x-kong-signature`, sent to the remote endpoint. (optional) + config.ssl_verify: + type: boolean + description: A boolean indicating whether to verify the SSL certificate of the remote HTTPS server where the event hook will be sent. + default: false + ping-event-hook: + description: Example response + content: + application/json: + schema: + type: object + properties: + source: + type: string + event_hooks: + type: object + properties: + source: + type: string + id: + type: string + on_change: + type: string + event: + type: string + handler: + type: string + created_at: + type: integer + config: + type: object + properties: + headers: + type: object + properties: + content-type: + type: string + ssl_verify: + type: boolean + url: + type: string + secret: + type: string + snooze: + type: string + event: + type: string + x-examples: + Example 1: + source: 'kong:event_hooks' + event_hooks: + source: crud + id: c57340ab-9fed-40fd-bb7e-1cef8d37c2df + on_change: null + event: consumers + handler: webhook + created_at: 1627581575 + config: + headers: + content-type: application/json + ssl_verify: false + url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + secret: null + snooze: null + event: ping + examples: + Pinged event hook: + value: + source: 'kong:event_hooks' + event_hooks: + source: crud + id: c57340ab-9fed-40fd-bb7e-1cef8d37c2df + on_change: "string" + event: consumers + handler: webhook + created_at: 1627581575 + config: + headers: + content-type: application/json + ssl_verify: false + url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + secret: "secret" + snooze: "null" + event: ping + requestBodies: + vault-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + prefix: env + name: env + description: This vault is used to retrieve Redis database access credentials. + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + properties: + prefix: + type: string + description: | + The unique prefix (or identifier) for this vault configuration. Use this prefix to load the right vault configuration and implementation when referencing secrets with the other entities. + example: env + name: + type: string + description: | + The name of the vault that's being added. The vault implementation must be installed in every Kong instance. + example: env + description: + type: string + description: | + The description of the vault object. + example: This vault is used to retrieve Redis database access credentials. + config: + type: object + description: | + The configuration properties for the vault, which can be found on the vaults' documentation page. + properties: + prefix: + type: string + example: SSL_ + tags: + type: array + description: | + An optional set of strings associated with the vault, used for grouping and filtering. + items: + type: string + examples: + Example 1: + value: + prefix: env + name: env + description: This vault is used to retrieve Redis database access credentials. + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + description: The request object for creating a new vault object. + target-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + properties: + upstream: + type: object + description: | + The unique identifier or the name of the upstream for which to update the target. + properties: + id: + type: string + example: 173a6cee-90d1-40a7-89cf-0329eca780a6 + description: The unique identifier or the name of the upstream for which to update the target. + weight: + default: 100 + description: The weight this target gets within the upstream load balancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + minimum: 0 + maximum: 65535 + tags: + type: array + description: An optional set of strings associated with the target for grouping and filtering. + items: + type: string + examples: + Example: + value: + upstream: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + weight: 100 + tags: + - string + description: The request body for creating a new target entity. + upstream-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + - x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + properties: + name: + type: string + description: This is a hostname, which must be equal to the `host` of a service. + example: my-upstream + algorithm: + type: string + description: | + Which load balancing algorithm to use. + enum: + - consistent-hashing + - least-connections + - round-robin + - latency + default: round-robin + example: round-robin + hash_on: + type: string + description: What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + hash_fallback: + type: string + description: What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no Consumer identified). Not available if hash_on is set to cookie. + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + example: none + hash_on_header: + type: string + description: The header name to take the value from as hash input. Only required when `hash_on` is set to header. + example: none + hash_fallback_header: + type: string + description: The header name to take the value from as hash input. Only required when hash_fallback is set to header. + default: none + example: none + hash_on_cookie: + type: string + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + example: none + hash_on_cookie_path: + type: string + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + default: / + example: / + hash_on_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + example: hash_value + hash_fallback_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + example: hash_value + hash_on_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + example: hash_value + hash_fallback_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + example: hash_value + slots: + type: integer + description: The number of slots in the load balancer algorithm. If the algorithm is set to `round-robin`, this setting determines the maximum number of slots. If the algorithm is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range 10-65536. + minimum: 10 + maximum: 65536 + default: 10000 + example: 5000 + healthchecks: + type: object + properties: + passive: + type: object + properties: + type: + type: string + description: Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, http and https options are equivalent. Accepted values are `tcp`, `http`, `https`, `grpc`, `grpcs`. + default: http + enum: + - tcp + - http + - https + - grpc + - grpcs + example: tcp + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=201`. With JSON, use an array. + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + example: + - 200 + - 201 + - 202 + items: + type: integer + enum: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: + type: integer + description: Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks. + default: 0 + example: 2 + unhealthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an array. + default: + - 429 + - 500 + - 503 + example: + - 500 + - 503 + items: + type: integer + enum: + - 429 + - 500 + - 503 + timeouts: + type: integer + description: Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + http_failures: + type: integer + description: Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 3 + tcp_failures: + type: integer + description: Number of TCP connection failures to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + active: + type: object + properties: + https_verify_certificate: + type: boolean + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an array. + default: + - 200 + - 302 + example: + - 200 + - 201 + items: + type: integer + successes: + type: integer + description: Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. + default: 0 + example: 3 + interval: + type: integer + description: Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. + default: 0 + example: 30 + unhealthy: + type: object + properties: + http_failures: + type: integer + description: Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. + default: 0 + example: 2 + http_statuses: + type: array + description: An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=404`. With JSON, use an array. + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + example: + - 400 + - 404 + items: + type: integer + timeouts: + type: integer + description: Number of timeouts in active probes to consider a target unhealthy. + default: 0 + example: 2 + tcp_failures: + type: integer + description: Number of TCP failures in active probes to consider a target unhealthy. + default: 0 + example: 1 + interval: + type: integer + description: Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. + default: 0 + example: 10 + type: + type: string + description: Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. + enum: + - tcp + - http + - https + - grpc + - grpcs + default: http + example: https + concurrency: + type: integer + description: Number of targets to check concurrently in active health checks. + default: 10 + example: 5 + headers: + type: object + description: One or more lists of values indexed by header name to use in GET HTTP request to run as a probe on active health checks. Values must be pre-formatted. + example: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: + type: integer + description: Socket timeout for active health checks (in seconds). + default: 1 + example: 5 + http_path: + type: string + description: Path to use in GET HTTP request to run as a probe on active health checks. + default: / + https_sni: + type: string + description: The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. This is particularly useful when Targets are configured using IPs, so that the target host's certificate can be verified with the proper SNI. + threshold: + type: integer + description: The minimum percentage of the upstream's targets' weight that must be available for the whole upstream to be considered healthy. + minimum: 0 + maximum: 100 + default: 0 + tags: + type: array + description: An optional set of strings associated with the Upstream for grouping and filtering. + example: + - user-level + - low-priority + items: + type: string + host_header: + type: string + description: The hostname to be used as Host header when proxying requests through Kong. + client_certificate: + type: object + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + example: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: + type: boolean + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host. + example: false + required: + - name + examples: + Upstream: + value: + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + Example request: + value: + name: my-upstream + tags: + - user-level + - low-priority + algorithm: round-robin + description: The request object for creating a new upstream. + service-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + properties: + name: + type: string + description: | + The service name. + example: my-service + retries: + type: integer + description: | + The number of retries to execute upon failure to proxy. Default:`5`. + default: 5 + example: 5 + protocol: + type: string + description: |- + The protocol used to communicate with the upstream. Accepted values are: "`grpc`", "`grpcs`", "`http`", "`https`", "`tcp`", "`tls`", "`tls_passthrough`", "`udp`", "`ws`" + , "`wss`" + . Default: "`http`". + default: http + enum: + - grpc + - grpcs + - http + - https + - tcp + - 'tls ' + - tls_passthrough + - udp + - ws + - wss + example: http + host: + type: string + description: | + The host of the upstream server. Note that the host value is case sensitive. + example: example.com + port: + type: integer + description: | + The upstream server port. Default: `80`. + default: 80 + example: 80 + path: + type: string + description: | + The path to be used in requests to the upstream server. + example: /some_api + connect_timeout: + type: integer + description: The timeout in milliseconds for establishing a connection to the upstream server. Default `60000`. + default: 6000 + example: 6000 + write_timeout: + type: integer + description: | + The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + read_timeout: + type: integer + description: | + The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + tags: + type: array + description: | + An optional set of strings associated with the service for grouping and filtering. + items: + type: string + example: user-level + client_certificate: + type: object + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is `client_certificate.id=`. With JSON, use `"client_certificate":{"id":""}`. + properties: + id: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: + type: boolean + description: | + Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected. + default: true + tls_verify_depth: + type: string + description: | + Maximum depth of chain while verifying Upstream server's TLS certificate. If set to null, then the Nginx default is respected. Default: null. + example: respected + default: null + nullable: true + ca_certificates: + type: array + description: Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream servers TLS certificate. If set to null when Nginx default is respected. With form-encoded, the notation is `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`. With JSON, use an array. + items: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: + type: boolean + default: true + description: Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). + required: + - protocol + - host + - port + - enabled + examples: + Example: + value: + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 6000 + write_timeout: 6000 + read_timeout: 6000 + tags: + - user-level + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: true + description: The request body for creating a new service entity. + route-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + snis: + - foo.test + - example.com + sources: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + destinations: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + properties: + name: + type: string + description: | + The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test". + protocols: + type: array + description: An array of the protocols this route should allow + items: + type: string + default: https + example: tcp + methods: + type: array + description: | + A list of HTTP methods that match this route. + items: + type: string + example: GET + hosts: + type: array + description: A list of domain names that match this route. Note that the hosts value is case sensitive. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array. + items: + type: string + paths: + type: array + description: A list of paths that match this route. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an array. The path can be a regular expression, or a plain text pattern. + items: + type: string + headers: + type: object + description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The Host header cannot be used with this attribute hosts should be specified using the `hosts` attribute. When headers contains only one value and that value starts with the special prefix` ~*`, the value is interpreted as a regular expression. + properties: + x-my-header: + type: array + items: + type: string + x-another-header: + type: array + items: + type: string + https_redirect_status_code: + type: integer + description: |- + The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS` + Location header is injected by Kong if the field is set to `301`, `302`, `307` or `308`. Note: This config applies only if the route is configured to only accept the https protocol. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`. + default: 426 + enum: + - 426 + - 301 + - 302 + - 307 + - 308 + example: 426 + regex_priority: + type: integer + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + default: 0 + example: 0 + strip_path: + type: boolean + description: When matching a route via one of the paths, strip the matching prefix from the upstream request URL. + default: true + path_handling: + type: string + description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. Accepted values are "`v0`", "`v1`". + enum: + - v1 + - v0 + example: v0 + preserve_host: + type: boolean + description: When matching a route via one of the `hosts` domain names, use the request `host` header in the upstream request headers. If set to `false`, the upstream Host header will be that of the service's host. + default: true + request_buffering: + type: boolean + default: true + description: | + Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true. + response_buffering: + type: boolean + default: true + description: | + Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: `true`. + snis: + type: array + description: | + A list of SNIs that match this route when using stream routing. + items: + type: string + sources: + type: array + description: | + A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 10.1.0.0/16 + port: + type: integer + example: 1234 + destinations: + type: array + description: | + A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 0.1.0.0/16 + port: + type: integer + tags: + type: array + description: | + An optional set of strings associated with the route for grouping and filtering. + items: + type: string + service: + type: object + description: The service this route is associated to. This is where the route proxies traffic to. With form-encoded, the notation is service.id= or service.name=. With JSON, use `"service":{"id":""}` or `"service":{"name":""}`. + nullable: true + properties: + id: + type: string + example: af8330d3-dbdc-48bd-b1be-55b98608834b + required: + - protocols + - https_redirect_status_code + - preserve_host + - request_buffering + - response_buffering + examples: + Create a route: + value: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + description: Route request body + keys-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + properties: + set: + type: object + description: The id (an UUID) of the key-set with which to associate the key .With form-encoded, the notation is `set.id=` or `set.name=`. With JSON, use `"set":{"id":""}` or `"set":{"name":""}.` + properties: + id: + type: string + description: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: + type: string + example: my-key + description: | + The name to associate with the given keys. + kid: + type: string + description: | + A unique identifier for a key. + example: '42' + jwk: + type: string + description: A JSON Web Key represented as a string. + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + pem: + type: object + description: | + A keypair in PEM format. + properties: + private_key: + type: string + example: 'private_key": "-----BEGIN' + public_key: + type: string + example: 'public_key": "-----BEGIN' + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + required: + - kid + description: The request body for creating a new key entity. + key-set-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-key_set + tags: + - google-keys + - mozilla-keys + properties: + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + description: The request body for creating a new key-set entity. + plugin-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: rate-limiting + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + properties: + name: + type: string + description: The name of the plugin that's being added. The plugin must be installed in every Kong instance separately. + example: rate-limiting + route: + type: string + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default `null`.With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique within a workspace for Kong Gateway Enterprise. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the plugin for grouping and filtering. + items: + type: string + ordering: + type: object + description: | + Describes a dependency to another plugin to determine plugin ordering during the access phase. + - `before`: The plugin will be executed before a specified plugin or list of plugins. + - `after`: The plugin will be executed after a specified plugin or list of plugins. + properties: + before: + type: array + items: + type: string + examples: + request example: + value: + name: rate-limiting + route: string + service: string + consumer: string + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 500 + protocols: + - http + enabled: true + tags: + - string + ordering: + before: + - string + description: Plugin request body + consumer-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + username: + type: string + description: | + The unique username of the Consumer. You must send either this field or custom_id with the request. + custom_id: + type: string + 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. + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + required: + - username + - custom_id + description: Consumer request body + create-sni: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-sni + tags: + - user-level + - low-priority + certificate: + id: a2e013e8-7623-4494-a347-6d29108ff68b + properties: + name: + type: string + description: The SNI name to associate with the given certificate. + example: my-sni + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + example: '["user-level", "low-priority"]' + certificate: + type: object + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is `certificate.id=`. With JSON, use `"certificate":{"id":""}`. + properties: + id: + type: string + example: 91020192-062d-416f-a275-9addeeaffaf2 + description: 91020192-062d-416f-a275-9addeeaffaf2 + required: + - name + - certificate + description: A JSON object containing the details of the new SNI, including the name, certificate, and tags. + cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example: + id: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + key: '-----BEGIN RSA PRIVATE KEY-----...' + cert_alt: '-----BEGIN CERTIFICATE-----...' + key_alt: '-----BEGIN EC PRIVATE KEY-----...' + snis: + - foo.test + - example.com + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: PEM-encoded public certificate chain of the SSL key pair. + example: '-----BEGIN CERTIFICATE-----...' + key: + type: string + example: '-----BEGIN RSA PRIVATE KEY-----...' + description: PEM-encoded private key of the SSL key pair. + cert_alt: + type: string + description: PEM-encoded public certificate chain of the alternate SSL key pair. + key_alt: + type: string + description: PEM-encoded private key of the alternate SSL key pair. + example: '"-----BEGIN EC PRIVATE KEY-----..."' + snis: + type: array + description: An array of zero or more hostnames to associate with this certificate as SNIs. + items: + type: string + tags: + type: array + description: | + An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + passphrase: + type: string + description: To load an encrypted private key into Kong, specify the passphrase using this attributKong will decrypt the private key and store it in its database. e. Enterprise Only + example: example + required: + - cert + - key + description: The certificate request body + CA-cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: | + PEM-encoded public certificate of the CA. + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + description: | + SHA256 hex digest of the public certificate. + tags: + type: array + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + required: + - cert + description: This request body represents a new Certificate Authority (CA) certificate and includes the properties required to create a new certificate. + consumer_group_request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + created_at: 1557522650 + id: fa6881b2-f49f-4007-9475-577cd21d34f4 + name: JL + tags: + - tag1 + - tag2 + properties: + name: + type: string + description: A unique name for the consumer group you want to create. + example: my_group + tags: + type: array + description: An optional set of strings associated with the consumer group for grouping and filtering. + items: + type: string + required: + - name + examples: + example consumer group request body: + value: + name: my_group + tags: + - string + description: The consumer groups request body for creating new consumer groups. + license-request: + content: + application/json: + schema: + type: object + properties: + payload: + type: string + description: | + The Kong Gateway license in JSON format. + example: '{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}' + description: The request body for uploading a license. + workspace-request: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: | + The workspace name. + example: my-workspace + description: | + The workspace object describes the workspace entity, which has an ID and a name. + rbac-request: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + description: | + The RBAC user name. + user_token: + type: string + + description: The authentication token to be presented to the Admin API. The value will be hashed and cannot be fetched in plaintext. + enabled: + type: string + + description: | + A flag to enable or disable the user. By default, users are enabled. + comment: + type: string + + description: | + A string describing the RBAC user object. + filter-chains-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: my-chain + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + - name: go-rate-limiting + enabled: true + config: '{ "minute": 30 }' + - name: rust-response-transformer + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: + - my-tag + properties: + ' name': + type: string + + description: | + The name of the filter chain. + example: my-chain + enabled: + type: string + + description: | + Whether the filter chain is applied. Default: true. + route: + type: string + + description: | + The route to which this chain is applied. + A filter chain must be applied to either a single route or a single service. + Default: `null`. + + In form-encoded format, the notation is `route.id=` or `route.name=`. + In JSON format, use `"route":{"id":""}` or `"route":{"name":""}`. + service: + type: string + + description: | + The service to which this chain is applied. + A filter chain must be applied to either a single route or a single service. Default: `null`. + + In form-encoded format, the notation is `service.id=` or `service.name=`. + In JSON format, use `"service":{"id":""}` or `"service":{"name":""}`. + example: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + type: string + + description: An array of filter definitions. Each filter is an object containing a mandatory name, an optional config, and a boolean enabled setting. + tags: + type: string + + description: | + An optional set of strings associated with the filter chain for grouping and filtering. + examples: + Example 1: + value: + ' name': my-chain + enabled: string + route: string + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: string + tags: string + description: A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + add-webhook: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: consumers + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: webhook + source: + type: string + + description: | + A string describing the action that triggers the event hook. + example: crud + snooze: + type: integer + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + example: 0 + default: 0 + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + config.url: + type: string + + description: | + The URL the JSON POST request is made to with the event data as the payload. + example: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + config.headers: + type: object + + description: | + An object defining additional HTTP headers to send in the webhook request. For example `{"X-Custom-Header": "My Value"}`. + properties: + headers: + type: string + + description: | + Optional configuration header + config.secret: + type: string + + description: | + An optional string used to sign the remote webhook for remote verification. When set, Kong signs the body of the event hook with HMAC-SHA1 and includes it in a header, `x-kong-signature`, sent to the remote endpoint. + config.ssl_verify: + type: string + + description: | + A boolean indicating whether to verify the SSL certificate of the remote HTTPS server where the event hook will be sent. The default is false. + required: + - handler + - source + - config.url + examples: + Example 2: + value: + event: consumers + handler: webhook + source: crud + snooze: 0 + on_change: true + config.url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + config.headers: + headers: string + config.secret: string + config.ssl_verify: string + description: Request body for adding a webhook + add-custom-webhook: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: admins + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: webhook-custom + source: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: crud + snooze: + type: integer + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + default: 1 + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + default: true + config.url: + type: string + + description: | + The URL the JSON POST request is made to with the event data as the payload. + example: 'https://hooks.slack.com/services/foo/bar/baz' + config.method: + type: string + + description: | + The HTTP method used to create the custom webhook. + example: GET + config.payload: + type: object + + description: | + An object that includes key/value pairs that describe the configurable payload body. Supports templating. The full list of available template parameters can be found in the /sources API output, under the fields JSON object. + properties: + text: + type: string + + description: Configuration payload + config.payload_format: + type: boolean + + description: | + A optional boolean (defaults to true) indicating whether to format `config.payload` with resty templating. When set to false, the payload is sent as a raw object. + config.body: + type: string + + description: | + An optional string sent in the remote request. + config.body_format: + type: boolean + + description: | + An optional boolean (defaults to true) indicating whether to format `config.body` with resty templating. When set to false, the body is sent as a raw object. To see all the available parameters defined for a specific source, check the source fields displayed by the `/event-hooks/source` endpoint. + config.headers: + type: object + + description: | + An object defining additional HTTP headers to send in the webhook request. For example `{"Content-type": "application/json", "X-Custom-Header": "My Value"}`. + config.headers_format: + type: string + + description: | + An optional boolean (defaults to false) indicating whether to format `config.headers` with resty templating. When set to true, the `config.headers` value is treated as a template. To see all the available parameters defined for a specific source, check the source fields displayed by the `/event-hooks/sources` endpoint. + config.secret: + type: string + + description: | + An optional string used to sign the remote webhook for remote verification. When set, Kong signs the body of the event hook with HMAC-SHA1 and includes it in a header, `x-kong-signature`, to the remote endpoint. + config.ssl_verify: + type: boolean + + required: + - handler + - source + - config.url + - config.method + description: Request body for adding a custom webhook + add-log: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: routes + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: log + source: + type: string + + description: | + A string describing the action that triggers the event hook. + example: crud + snooze: + type: integer + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + required: + - handler + - source + examples: + Example log request: + value: + event: routes + handler: log + source: crud + snooze: 0 + on_change: true + description: Add a log event hook request body + lambda-event-hook: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: consumers + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: lambda + source: + type: string + + description: | + A string describing the action that triggers the event hook. + example: crud + snooze: + type: boolean + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + config.functions: + type: array + + description: | + An array of Lua code functions to execute on the event hook. + items: + + type: string + example: '"functions": [ "return function (data, event, source, pid)\n local user = data.entity.username\n error(\"Event hook on consumer \" .. user .. \"\")\nend\n" ]' + required: + - handler + - source + - config.functions + examples: + lambda-event-hook: + value: + event: consumers + handler: lambda + source: crud + snooze: true + on_change: true + config.functions: + - '"functions": [ "return function (data, event, source, pid)\n local user = data.entity.username\n error(\"Event hook on consumer \" .. user .. \"\")\nend\n" ]' + description: Request body for adding a lambda event hook + securitySchemes: + kongAdminToken: + type: apiKey + in: header + name: Kong-Admin-Token + description: | + When RBAC is enabled, an admin token is required to use the Kong Admin API. + This token is passed in a `Kong-Admin-Token` header by default. + To configure the header name, adjust `rbac_auth_header` in `kong.conf`. +

+ Each admin has their own token. + The admin associated with the token must have relevant permissions for the object they're interacting with. + Generate tokens using the `/admins` API. +

+ If RBAC isn't enabled, this token isn't required. + +externalDocs: + description: Kong Gateway Enterprise Admin API + url: 'https://docs.konghq.com' +info: + contact: + email: docs@konghq.com + name: Kong Inc + url: 'https://konghq.com' + description: |- + OpenAPI 3.0 spec for Kong Gateway's Enterprise Admin API. + + You can learn more about Kong Gateway at [docs.konghq.com](https://docs.konghq.com) + .Give Kong a star at [Kong/kong](https://github.com/kong/kong) repository. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + title: Enterprise Kong Admin API + version: 3.8.0 +openapi: 3.0.0 +paths: + /: + get: + summary: Get Kong's instance information + tags: + - Information + operationId: geInfo + description: | + Returns detailed information about the Kong gateway instance, including the full Kong configuration, available and unavailable plugins, version, edition (enterprise or community), a tagline, the unique node identifier, and other metadata. + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + version: + type: string + description: The version number of the Kong instance. + example: "2.3.3" + edition: + type: string + description: Indicates whether the Kong instance is the Community or Enterprise edition. + example: "enterprise" + tagline: + type: string + description: A tagline or slogan for the Kong instance. + example: "Welcome to Kong" + node_id: + type: string + description: A unique identifier for the node, in UUID format. + format: uuid + example: "a74d7c4f-ef83-4bbe-a5e7-3f5409f4a0b9" + hostname: + type: string + description: The hostname of the Kong node. + example: "kong-node.example.com" + timers: + type: object + description: Information about running and pending timers. + properties: + running: + type: integer + description: The number of running timers. + example: 5 + pending: + type: integer + description: The number of pending timers. + example: 2 + plugins: + type: object + description: Information about plugins. + properties: + available_on_server: + type: object + additionalProperties: + type: object + properties: + version: + type: string + description: The version of the plugin. + priority: + type: integer + description: The priority of the plugin. + enabled_in_cluster: + type: array + items: + type: string + description: A list of distinct plugin names enabled in the cluster. + example: ["jwt", "acl"] + lua_version: + type: string + description: The version of Lua used by the Kong instance. + example: "LuaJIT 2.1.0-beta3" + configuration: + type: object + description: A sanitized version of the Kong configuration, excluding sensitive values. + additionalProperties: true + pids: + type: object + description: Process IDs for the master process and worker processes. + properties: + master: + type: integer + description: The PID of the master process. + example: 4321 + workers: + type: array + items: + type: integer + description: An array of worker process PIDs. + example: [1234, 5678] + examples: + fullExample: + summary: Example response + value: + configuration: + _debug_pg_ttl_cleanup_interval: 300 + admin_acc_logs: "/usr/local/kong/logs/admin_access.log" + admin_access_log: "/dev/stdout" + admin_approved_email: "true" + admin_emails_from: "\"\"" + admin_error_log: "/dev/stderr" + admin_gui_access_log: "logs/admin_gui_access.log" + admin_gui_auth_header: "******" + admin_gui_auth_login_attempts: 0 + admin_gui_error_log: "logs/admin_gui_error.log" + admin_gui_flags: "{}" + admin_gui_listen: + - "0.0.0.0:8002" + - "0.0.0.0:8445 ssl" + admin_gui_origin: "http://localhost:8002" + edition: "enterprise" + hostname: "8a487998603b" + lua_version: "LuaJIT 2.1.0-20231117" + node_id: "1f257156-5e44-46e2-a618-767f5c7529e3" + pids: + master: 1 + workers: + - 2382 + - 2383 + plugins: + available_on_server: + acl: true + acme: true + disabled_on_server: + application-registration: true + enabled_in_cluster: [] + tagline: "Welcome to kong" + timers: + pending: 1 + running: 1128 + version: "3.6.0.0" + '401': + $ref: '#/components/responses/HTTP401Error' + '405': + description: Method Not Allowed + content: + application/json: + schema: + $ref: '#/components/schemas/UnauthorizedError' + headers: + Server: + description: Kong's server tokens. + schema: + type: string + example: "kong/2.3.3" + /ca_certificates: + get: + description: Retrieve a list of all available Certificate Authority (CA) certificates, including the certificate ID, creation date, and other details. You can use query parameters to filter the results by size or tags, for example `/ca-certificates?size=50&tags=enterprise`. + operationId: list-ca_certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: A successful response listing CA Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all CA Certificates + tags: + - CA Certificates + post: + description: Create a new Certificate Authority (CA) certificate. The request body must include the `cert` property, the certificate data in PEM format; it can also include `cert_digest`, a digest of the certificate in hex format for verifying the certificates integrity, and `tags`, an optional list of tags to categorize the certificate. + operationId: create-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully created CA Certificate + '400': + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + cert: 'invalid certificate: x509.new: asn1/a_d2i_fp.c:197:error:0D06B08E:asn1 encoding routines:asn1_d2i_read_bio:not enough data' + message: 'schema violation (cert: invalid certificate: x509.new: asn1/a_d2i_fp.c:197:error:0D06B08E:asn1 encoding routines:asn1_d2i_read_bio:not enough data)' + name: schema violation + code: 2 + properties: + fields: + type: object + properties: + cert: + type: string + description: Error information about the certificate. + example: 'invalid certificate: x509.new:' + message: + type: string + description: More information about the error + example: 'schema violation (cert: invalid certificate: x509.new:' + name: + type: string + description: The name of the error. + example: schema violation + code: + type: integer + description: An error code. + example: 2 + examples: + invalid certificate: + value: + fields: + cert: 'invalid certificate: x509.new:' + message: 'schema violation (cert: invalid certificate: x509.new:' + name: schema violation + code: 2 + description: 400 Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + '/ca_certificates/{ca_certificate_id}': + delete: + description: Delete the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. + operationId: delete-ca_certificate + responses: + '204': + description: Successfully deleted CA Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a CA Certificate + tags: + - CA Certificates + get: + description: Retrieve details about the specified Certificate Authority (CA) certificate using the provided path parameter `ca_certificate_id`. + operationId: get-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully fetched CA Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a CA Certificate + tags: + - CA Certificates + patch: + description: Update a CA Certificate + operationId: update-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully updated CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + put: + description: Update the specified Certificate Authority (CA) certificate using the provided `ca_certificate_id`. Use this endpoint to modify an existing CA certificate in the system. The request body should include the fields of the CA certificate that need to be updated. + operationId: upsert-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully upserted CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '404': + description: Not Found + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + parameters: + - $ref: '#/components/parameters/ca_certificate_id' + /certificates: + get: + description: Retrieve a list of all available CA Certificate Authority (CA) certificates. You can use query parameters to filter the results by size or tags, for example `/certificates?size=50&tags=enterprise`. + operationId: list-certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + examples: + Certificate: + value: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + description: A successful response listing Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Certificates + tags: + - Certificates + post: + description: Create a new certificate with the provided details. Use this endpoint to add a new certificate to the system. The request body must include the certificate data and other details required for creating a new certificate. + operationId: create-certificate + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Description of the new Certificate for creation + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + key: 'invalid key: pkey.new:load_key: pem/pem_lib.c:949:error:09091064:PEM routines:PEM_read_bio_ex:bad base64 decode' + cert: 'invalid certificate: x509.new: asn1/tasn_dec.c:309:error:0D07803A:asn1 encoding routines:asn1_item_embed_d2i:nested asn1 error' + message: '2 schema violations (cert: invalid certificate: x509.new: asn1/tasn_dec.c:309:error:0D07803A:asn1 encoding routines:asn1_item_embed_d2i:nested asn1 error; key: invalid key: pkey.new:load_key: pem/pem_lib.c:949:error:09091064:PEM routines:PEM_read_bio_ex:bad base64 decode)' + name: schema violation + code: 2 + properties: + fields: + type: object + properties: + key: + type: string + description: Information about the key. + example: 'invalid key: pkey.new:load_key: ' + cert: + type: string + description: Information about the certificate. + example: 'invalid certificate: x509.new: ' + message: + type: string + description: error message + example: '2 schema violations (cert: invalid certificate: x509.new: asn1/tasn_dec.c:309:error:0D07803A:asn1' + name: + type: string + description: The name of the error message. + example: schema violation + code: + type: integer + description: An error code. + example: 2 + examples: + Example 1: + value: + fields: + key: string + cert: string + message: string + name: string + code: 0 + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Certificate + tags: + - Certificates + '/certificates/{certificate_id}': + delete: + description: Delete a Certificate + operationId: delete-certificate + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Certificate + tags: + - Certificates + get: + description: Get a Certificate using ID. + operationId: get-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully fetched Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Certificate + tags: + - Certificates + patch: + description: | + Update a Certificate + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + operationId: update-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + put: + description: | + Update details about the specified certificate using the provided path parameter `certificate_id`. + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + operationId: upsert-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/certificate_id' + '/certificates/{certificate_name_or_id}/snis': + get: + description: Retrieve a paginated list of all SNIs associated with a certificate. Use this endpoint to retrieve a list of SNIs that are linked to a specific certificate. You can use the optional query parameters to filter the results based on specific criteria. The response will include the list of SNIs and pagination information. See the response schema for details on the expected format of the response body. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/SNI' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing SNIs + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs associated with a Certificate + tags: + - SNIs + operationId: list-sni-with-certificate + post: + description: Create a new SNI and associate it with a certificate in the system. Use this endpoint to add a new SNI to the system and link it to a specific certificate. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully created SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI associated with a Certificate + tags: + - SNIs + operationId: create-sni-with-certificate + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + '/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: | + Delete a an SNI associated with a Certificate using ID or name. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a an SNI associated with a Certificate + tags: + - SNIs + operationId: delete-sni-with-cert + get: + description: Get an SNI associated with a Certificate using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully fetched SNI + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch an SNI associated with a Certificate + tags: + - SNIs + operationId: fetch-sni-with-cert + patch: + description: Update an existing SNI associated with a certificate in the system using the SNI ID or name. The request body should include the fields of the SNI that need to be updated, such as the name, description, or other properties. If the request body contains valid data, the endpoint will update the SNI and return a success response. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully updated SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a an SNI associated with a Certificate + tags: + - SNIs + operationId: update-sni-with-cert + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: | + Create or Update an SNI associated with a Certificate using ID or name. + + Inserts (or replaces) the SNI under the requested resource with the definition specified in the body. The SNI will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the SNI being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new SNI without specifying id (neither in the URL nor in the body), then it will be auto-generated. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully upserted SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert an SNI associated with a Certificate + tags: + - SNIs + operationId: upsert-sni-with-cert + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/certificate_id' + - $ref: '#/components/parameters/sni_name_or_id' + /consumers: + get: + description: Retrieve a list of all consumers.You can use query parameters to filter the results by size or tags, for example `/consumers?size=50&tags=enterprise`. + operationId: list-consumer + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + summary: List all Consumers + tags: + - Consumers + post: + description: Create a new Consumer + operationId: create-consumer + responses: + '201': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '409': + description: Conflict + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + username: stri22ng + message: UNIQUE violation detected on `{username="stri22ng"}` + name: unique constraint violation + code: 5 + properties: + fields: + type: object + description: An array of fields that may have caused the error. + properties: + username: + type: string + description: The username that triggerd the conflict. + example: stri22ng + message: + type: string + description: Detail about the conflict. + example: UNIQUE violation detected on `{username=\"stri22ng\"}` + name: + type: string + description: THe name of the violation. + example: unique constraint violation + code: + type: integer + description: Error code for debugging purposes. + example: 5 + examples: + Constraint violation: + value: + fields: + username: stri22ng + message: UNIQUE violation detected on `{username="stri22ng"}` + name: unique constraint violation + code: 5 + summary: Create a new Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + '/consumers/{consumer_username_or_id}': + delete: + description: Delete a Consumer + operationId: delete-consumer + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Consumer + tags: + - Consumers + get: + description: | + Retrieve the details of a specific consumer in the system using either the consumer ID or the consumer username. If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: get-consumer + responses: + '200': + $ref: '#/components/responses/consumer_response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a consumer + tags: + - Consumers + patch: + description: | + Update the details of a specific consumer in the system using either the consumer ID or the consumer username.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: update-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully updated Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: |- + Create or Update Consumer using ID or username. The consumer will be identified via the username or id attribute.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + + When the username or id attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its id. Otherwise it will be identified by its username. + + When creating a new Consumer without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a username in the URL and a different one in the request body is not allowed. + operationId: upsert-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully upserted Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a consumer + tags: + - Plugins + operationId: list-plugins-with-consumer + post: + description: Create a new plugin associated with a Consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a consumer + tags: + - Plugins + operationId: create-plugin-for-consumer + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_name_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a aconsumer using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a consumer + tags: + - Plugins + operationId: delete-plugin-for-consumer + get: + description: Get a plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '404': + description: Not Found + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: Not found + properties: + message: + type: string + example: Not Found + description: 404 Not Found + examples: + Not Found: + value: + message: Not Found + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a plugin associated with a Consumer + tags: + - Plugins + operationId: fetch-plugin-with-consumer + patch: + description: Update a plugin associated with a consumer using the consumer username or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a consumer + tags: + - Plugins + operationId: update-plugin-with-consumer + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update a plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-customer + parameters: + - $ref: '#/components/parameters/consumer_name_or_id' + - $ref: '#/components/parameters/plugin_id' + /key-sets: + get: + description: | + Retrieve a list of all Key-sets in the system. A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. Key Sets can be both tagged and filtered by tags. + operationId: list-key-set + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Key-sets + tags: + - Key-sets + post: + description: | + This endpoint allows creating a new Key-set by sending a JSON object that describes the Key-set to be created.The request body must contain all the fields required to create a new Key-set. + operationId: create-key-set + responses: + '201': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '409': + description: Conflict + content: + application/json: + schema: + type: object + properties: + fields: + type: object + properties: + name: + type: string + message: + type: string + name: + type: string + code: + type: integer + x-examples: + Example 1: + fields: + name: my-key_set + message: UNIQUE violation detected on `{name="my-key_set"}` + name: unique constraint violation + code: 5 + examples: + Not Found: + value: + fields: + name: my-key_set + message: UNIQUE violation detected on `{name="my-key_set"}` + name: unique constraint violation + code: 5 + summary: Create a new Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + '/key-sets/{key-set_id_or_name}': + delete: + description: Delete a Key-set + operationId: delete-key-set + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key-set + tags: + - Key-sets + get: + description: | + Get a Key-set using ID or name. This endpoint retrieves information about a specific key-set based on its ID or name. + operationId: get-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Key-set + tags: + - Key-sets + patch: + description: |- + Update a Key-set using ID or name. + + Note: This API is not available in DB-less mode. + + Inserts (or replaces) the Key Set under the requested resource with the definition specified in the body. The Key Set will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the Key Set being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new Key Set without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + operationId: update-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: | + Update a Key-set using ID or name. + operationId: upsert-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/key-set_id_or_name' + /keys: + get: + description: List all Keys + operationId: list-key + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Key' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Keys + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Keys + tags: + - Keys + post: + description: This API endpoint allows you to create a new key. When the request is successful, the API will respond with a 200 status code and a JSON object that represents the newly created key. If the request is invalid, the API will respond with a 400 status code and an error message in the response body. + operationId: create-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + '/keys/{key_id_or_name}': + delete: + description: Delete a Key + operationId: delete-key + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + summary: Delete a Key + tags: + - Keys + get: + description: Get a Key using ID or name. + operationId: get-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully fetched Key + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Key + tags: + - Keys + patch: + description: Update a Key + operationId: update-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: | + Create or update a key using ID or name. + operationId: upsert-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/key_id_or_name' + /plugins: + get: + description: | + List all plugins + + operationId: list-plugin + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins + tags: + - Plugins + post: + description: Create a new plugin + operationId: create-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + '/plugins/{plugin_id}': + delete: + description: Delete a plugin + operationId: delete-plugin + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin + tags: + - Plugins + get: + description: Get a plugin using ID. + operationId: get-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a plugin + tags: + - Plugins + patch: + description: Update a plugin + operationId: update-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update plugin using ID. + operationId: upsert-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/plugin_id' + /routes: + get: + description: |- + List all routes + + route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to its associated service. + + Note: Path handling algorithms v1 was deprecated in Kong 3.0. From Kong 3.0, when router_flavor is set to expressions, route.path_handling will be unconfigurable and the path handling behavior will be "v0"; when router_flavor is set to traditional_compatible, the path handling behavior will be "v0" regardless of the value of route.path_handling. Only router_flavor = traditional will support path_handling "v1' behavior. + operationId: list-route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes + tags: + - Routes + post: + description: Create a new route + operationId: create-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + '/routes/{route_id_or_name}': + delete: + description: Delete a route + operationId: delete-route + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route + tags: + - Routes + get: + description: Get a route using ID or name. + operationId: get-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route + tags: + - Routes + patch: + description: Update a route + operationId: update-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: Create or update a route using ID or name. + operationId: upsert-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins': + get: + description: List all plugins associated with a route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a route + tags: + - Plugins + operationId: list-plugins-with-route + post: + description: Create a new plugin associated with a route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a route using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a route + tags: + - Plugins + operationId: delete-plugin-with-route + get: + description: Get a plugin associated with a route using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a route + tags: + - Plugins + operationId: fetch-plugin-with-route + patch: + description: Update a plugin associated with a route using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-route + put: + description: Create or Update a plugin associated with a route using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + /services: + get: + description: List all Services + operationId: list-service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Service' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Services + '401': + $ref: '#/components/responses/HTTP401Error' + + summary: List all services + tags: + - Services + post: + description: Create a new service + operationId: create-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + '/services/{service_id_or_name}': + delete: + description: Delete a Service + operationId: delete-service + responses: + '204': + description: Successfully deleted Service or the resource didn't exist + summary: Delete a Service + tags: + - Services + get: + description: Get a Service using ID or name. + operationId: get-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched Service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Service + tags: + - Services + patch: + description: Update a Service + operationId: update-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update Service using ID or name. + operationId: upsert-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins': + get: + description: List all plugins associated with a Service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + summary: List all plugins associated with a Service + tags: + - Plugins + operationId: list-plugins-with-service + post: + description: Create a new plugin associated with a Service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a Service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a Service using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + summary: Delete a plugin associated with a Service + tags: + - Plugins + operationId: delete-plugin-with-service + get: + description: Get a plugin associated with a Service using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a Service + tags: + - Plugins + operationId: fetch-plugin-with-service + patch: + description: Update a plugin associated with a Service using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a Service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-service + put: + description: Create or Update a plugin associated with a Service using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a Service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes associated with a Service + tags: + - Routes + operationId: list-routes-with-service + post: + description: Create a new route associated with a Service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route associated with a Service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a Service using ID or name. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route associated with a Service + tags: + - Routes + operationId: delete-route-with-service + get: + description: Get a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route associated with a Service + tags: + - Routes + operationId: fetch-route-with-service + patch: + description: Update a route associated with a Service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route associated with a Service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-with-service + put: + description: Create or Update a route associated with a Service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route associated with a Service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + /snis: + get: + description: List all SNIs + operationId: list-sni + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs + tags: + - SNIs + post: + description: Create a new SNI + operationId: create-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + '/snis/{sni_name_or_id}': + delete: + description: Delete an SNI + operationId: delete-sni + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an SNI + tags: + - SNIs + get: + description: Get an SNI using ID or name. + operationId: get-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI + tags: + - SNIs + patch: + description: Update an SNI + operationId: update-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name. + operationId: upsert-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/sni_name_or_id' + /upstreams: + get: + description: | + List all registered upstreams. You can filter the results by pagination size, offset, or tags like /upstreams?size=10&offset=0. + operationId: list-upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Upstreams + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Upstreams + tags: + - Upstreams + post: + description: Create a new Upstream + operationId: create-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + '/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream + operationId: delete-upstream + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an Upstream + tags: + - Upstreams + get: + description: Get an Upstream using ID or name. + operationId: get-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an Upstream + tags: + - Upstreams + patch: + description: Update an Upstream + operationId: update-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name. + operationId: upsert-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Target' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Targets + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Targets associated with an Upstream + tags: + - Targets + operationId: list-target-with-upstream + post: + description: Create a new Target associated with an Upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-with-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + summary: Delete a Target associated with a an Upstream + tags: + - Targets + operationId: delete-target-with-upstream + get: + description: Get a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream + tags: + - Targets + operationId: fetch-target-with-upstream + patch: + description: Update a Target associated with a an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Target associated with a an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-with-upstream + put: + description: Create or Update a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-with-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + /vaults: + get: + description: List all Vaults + operationId: list-vault + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Vaults + tags: + - Vaults + post: + description: Create a new Vault + operationId: create-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + '/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault + operationId: delete-vault + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Vault + tags: + - Vaults + get: + description: | + Fetch a Vault using ID or prefix. + + Vault entities are used to configure different Vault connectors. + operationId: get-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Vault + tags: + - Vaults + patch: + description: Update a Vault + operationId: update-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix. + operationId: upsert-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/vault_id_or_prefix' + /workspaces: + get: + description: |- + List all Workspaces + + For workspace use cases and configuration examples, see [Workspace examples](https://docs.konghq.com/gateway/latest/kong-enterprise/workspaces/). This endpoint will only return workspaces that the current user has access to. + operationId: list-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Workspace' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Workspaces + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Workspaces + tags: + - Workspaces + post: + description: | + Create a new Workspace + + For workspace use cases and configuration examples, see [Workspace examples](https://docs.konghq.com/gateway/3.2.x/kong-enterprise/workspaces/). + operationId: create-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Description of the new Workspace for creation + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully created Workspace + '400': + content: + application/json: + schema: + type: object + description: Invalid Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Workspace + tags: + - Workspaces + '/workspaces/{workspace_id_or_name}': + delete: + description: Delete a Workspace + operationId: delete-workspace + responses: + '204': + description: Successfully deleted Workspace or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Workspace + tags: + - Workspaces + parameters: + - schema: + type: boolean + example: true + in: query + name: cascade + description: The `cascade` option lets you delete a workspace and all of its entities in one request. + get: + description: Get a Workspace using ID or name. + operationId: get-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully fetched Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Workspace + tags: + - Workspaces + patch: + description: Update a Workspace + operationId: update-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Fields of the Workspace that need to be updated + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully updated Workspace + '400': + content: + application/json: + schema: + type: object + description: Invalid Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Workspace + tags: + - Workspaces + put: + description: Create or Update Workspace using ID or name. + operationId: upsert-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Description of the Workspace + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully upserted Workspace + '400': + content: + application/json: + schema: + type: object + description: Invalid Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Workspace + tags: + - Workspaces + parameters: + - $ref: '#/components/parameters/workspace_id_or_name' + '/{workspace}/certificates': + get: + description: List all Certificates in a workspace + operationId: list-certificate-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Certificate' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Certificates in a workspace + tags: + - Certificates + post: + description: Create a new Certificate in a workspace + operationId: create-certificate-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Certificate in a workspace + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/certificates/{certificate_id}': + delete: + description: Delete a Certificate in a workspace + operationId: delete-certificate-in-workspace + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Certificate in a workspace + tags: + - Certificates + get: + description: Get a Certificate using ID in a workspace. + operationId: get-certificate-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully fetched Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Certificate in a workspace + tags: + - Certificates + patch: + description: Update a Certificate in a workspace + operationId: update-certificate-in-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Fields of the Certificate that need to be updated + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Certificate in a workspace + tags: + - Certificates + put: + description: Create or Update Certificate using ID in a workspace. + operationId: upsert-certificate-in-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Description of the Certificate + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Certificate in a workspace + tags: + - Certificates + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/certificate_id' + '/{workspace}/certificates/{certificate_id}/snis': + get: + description: List all SNIs associated with a Certificate in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs associated with a Certificate in a workspace + tags: + - SNIs + operationId: list-sni-with-cert-in-workspace + post: + description: Create a new SNI associated with a Certificate in a workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI associated with a Certificate in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: create-sni-with-cert-in-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/certificate_id' + '/{workspace}/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: Delete a an SNI associated with a Certificate using ID or name in a workspace. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + summary: Delete an SNI associated with a Certificate in a workspace + tags: + - SNIs + operationId: delete-sni-with-cert-in-workspace + get: + description: Get an SNI associated with a Certificate using ID or name in a workspace. + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI associated with a Certificate in a workspace + tags: + - SNIs + operationId: fetch-sni-with-cert-in-workspace + patch: + description: Update a an SNI associated with a Certificate using ID or name in a workspace. + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI associated with a Certificate in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: update-sni-with-cert-in-workspace + put: + description: Create or Update an SNI associated with a Certificate using ID or name in a workspace. + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert an SNI associated with a Certificate in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: upsert-sni-with-cert-in-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/certificate_id' + - $ref: '#/components/parameters/sni_name_or_id' + '/{workspace}/consumers': + get: + description: List all Consumers in a workspace + operationId: list-consumer-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Consumers in a workspace + tags: + - Consumers + post: + description: Create a new Consumer in a workspace + operationId: create-consumer-in-workspace + parameters: + - description: Name or ID of workspace + example: team-a + in: path + name: workspace + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Consumer in a workspace + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/consumers/{consumer_username_or_id}': + delete: + description: Delete a Consumer in a workspace + operationId: delete-consumer-in-workspace + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Consumer in a workspace + tags: + - Consumers + get: + description: Get a Consumer using ID or username in a workspace. + operationId: get-consumer-in-workspace + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Consumer in a workspace + tags: + - Consumers + patch: + description: Update a Consumer in a workspace + operationId: update-consumer-in-workspace + responses: + '200': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Consumer in a workspace + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: Create or Update Consumer using ID or username in a workspace. + operationId: upsert-consumer-in-workspace + responses: + '200': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Consumer in a workspace + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + '/{workspace}/consumers/{consumer_username_or_id}/plugins': + get: + description: List all plugins associated with a Consumer in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a Consumer in a workspace + tags: + - Plugins + operationId: list-plugins-consumer-workspace + post: + description: Create a new plugin associated with a Consumer in a workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a Consumer in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-consumer-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + '/{workspace}/consumers/{consumer_username_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a Consumer using ID in a workspace. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a Consumer in a workspace + tags: + - Plugins + operationId: delete-plugin-with-consumer-workspace + get: + description: Get a plugin associated with a Consumer using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a plugin associated with a Consumer in a workspace + tags: + - Plugins + operationId: fetch-plugin-with-consumer-workspace + patch: + description: Update a plugin associated with a Consumer using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a Consumer in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-consumer-workspace + put: + description: Create or Update a plugin associated with a Consumer using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-consumer-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/key-sets': + get: + description: List all Key-sets in a workspace + operationId: list-key-set-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Key-sets in a workspace + tags: + - Key-sets + post: + description: Create a new Key-set in a workspace + operationId: create-key-set-in-workspace + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key-set in a workspace + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/key-sets/{key-set_id_or_name}': + delete: + description: Delete a Key-set in a workspace + operationId: delete-key-set-in-workspace + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key-set in a workspace + tags: + - Key-sets + get: + description: Get a Key-set using ID or name in a workspace. + operationId: get-key-set-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key-set' + description: Successfully fetched Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Key-set in a workspace + tags: + - Key-sets + patch: + description: Update a Key-set in a workspace + operationId: update-key-set-in-workspace + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key-set in a workspace + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: Create or Update Key-set using ID or name in a workspace. + operationId: upsert-key-set-in-workspace + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key-set in a workspace + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/key-set_id_or_name' + '/{workspace}/keys': + get: + description: List all Keys in a workspace + operationId: list-key-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example 1: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Keys in a workspace + tags: + - Keys + post: + description: Create a new Key in a workspace + operationId: create-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Successfully created Key: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key in a workspace + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/keys/{key_id_or_name}': + delete: + description: Delete a Key in a workspace + operationId: delete-key-in-workspace + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key in a workspace + tags: + - Keys + get: + description: Get a Key using ID or name in a workspace. + operationId: get-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example 1: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully fetched Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Key in a workspace + tags: + - Keys + patch: + description: Update a Key in a workspace + operationId: update-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key in a workspace + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: Create or Update Key using ID or name in a workspace. + operationId: upsert-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example 1: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key in a workspace + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/key_id_or_name' + '/{workspace}/plugins': + get: + description: List all plugins in a workspace + operationId: list-plugin-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + summary: List all plugins in a workspace + tags: + - Plugins + post: + description: Create a new plugin in a workspace + operationId: create-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/plugins/{plugin_id}': + delete: + description: Delete a plugin in a workspace + operationId: delete-plugin-in-workspace + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + summary: Delete a plugin in a workspace + tags: + - Plugins + get: + description: Get a plugin using ID in a workspace. + operationId: get-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin in a workspace + tags: + - Plugins + patch: + description: Update a plugin in a workspace + operationId: update-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update plugin using ID in a workspace. + operationId: upsert-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/routes': + get: + description: List all routes in a workspace + operationId: list-route-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes in a workspace + tags: + - Routes + post: + description: Create a new route in a workspace + operationId: create-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route in a workspace + tags: + - Routes + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/routes/{route_id_or_name}': + delete: + description: Delete a route in a workspace + operationId: delete-route-in-workspace + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route in a workspace + tags: + - Routes + get: + description: Get a route using ID or name in a workspace. + operationId: get-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route in a workspace + tags: + - Routes + patch: + description: Update a route in a workspace + operationId: update-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: Create or Update route using ID or name in a workspace. + operationId: upsert-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/route_id_or_name' + '/{workspace}/routes/{route_id_or_name}/plugins': + get: + description: List all plugins associated with a route in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a route in a workspace + tags: + - Plugins + operationId: list-plugins-with-route-workspace + post: + description: Create a new plugin associated with a route in a workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a route in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-route-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/route_id_or_name' + '/{workspace}/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a route using ID in a workspace. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a route in a workspace + tags: + - Plugins + operationId: delete-plugin-with-route-workspace + get: + description: Get a plugin associated with a route using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a route in a workspace + tags: + - Plugins + operationId: fetch-plugin-with-route-workspace + patch: + description: Update a plugin associated with a route using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a route in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-route-workspace + put: + description: Create or Update a plugin associated with a route using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a route in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-route-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/services': + get: + description: List all Services in a workspace + operationId: list-service-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: A successful response listing Services + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Services in a workspace + tags: + - Services + post: + description: Create a new Service in a workspace + operationId: create-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Service in a workspace + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/services/{service_id_or_name}': + delete: + description: Delete a Service in a workspace + operationId: delete-service-in-workspace + responses: + '204': + description: Successfully deleted Service or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Service in a workspace + tags: + - Services + get: + description: Get a Service using ID or name in a workspace. + operationId: get-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched Service + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Service in a workspace + tags: + - Services + patch: + description: Update a Service in a workspace + operationId: update-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Service in a workspace + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update Service using ID or name in a workspace. + operationId: upsert-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Service in a workspace + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + '/{workspace}/services/{service_id_or_name}/plugins': + get: + description: List all plugins associated with a Service in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: List all plugins associated with a Service in a workspace + tags: + - Plugins + operationId: list-plugins-with-service-workspace + post: + description: Create a new plugin associated with a Service in a workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a Service in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + '/{workspace}/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a Service using ID in a workspace. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + summary: Delete a plugin associated with a Service in a workspace + tags: + - Plugins + operationId: delete-plugin-with-service-workspace + get: + description: Get a plugin associated with a Service using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a Service in a workspace + tags: + - Plugins + operationId: fetch-plugin-with-service-workspace + patch: + description: Update a plugin associated with a Service using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a Service in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-service-workspace + put: + description: Create or Update a plugin associated with a Service using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Service in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a Service in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: A successful response listing routes + summary: List all routes associated with a Service in a workspace + tags: + - Routes + operationId: list-routes-with-service-workspace + post: + description: Create a new route associated with a Service in a workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route associated with a Service in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + '/{workspace}/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a Service using ID or name in a workspace. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route associated with a Service in a workspace + tags: + - Routes + operationId: delete-route-with-service-workspace + get: + description: Get a route associated with a Service using ID or name in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route associated with a Service in a workspace + tags: + - Routes + operationId: fetch-route-with-service-workspace + patch: + description: Update a route associated with a Service using ID or name in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route associated with a Service in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-with-service-workspace + put: + description: Create or Update a route associated with a Service using ID or name in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route associated with a Service in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + '/{workspace}/snis': + get: + description: List all SNIs in a workspace + operationId: list-sni-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs in a workspace + tags: + - SNIs + post: + description: Create a new SNI in a workspace + operationId: create-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/snis/{sni_name_or_id}': + delete: + description: Delete an SNI in a workspace + operationId: delete-sni-in-workspace + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an SNI in a workspace + tags: + - SNIs + get: + description: Get an SNI using ID or name in a workspace. + operationId: get-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI in a workspace + tags: + - SNIs + patch: + description: Update an SNI in a workspace + operationId: update-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name in a workspace. + operationId: upsert-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a SNI in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/sni_name_or_id' + '/{workspace}/upstreams': + get: + description: List all Upstreams in a workspace + operationId: list-upstream-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Upstreams + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Upstreams in a workspace + tags: + - Upstreams + post: + description: Create a new Upstream in a workspace + operationId: create-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Upstream in a workspace + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream in a workspace + operationId: delete-upstream-in-workspace + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an Upstream in a workspace + tags: + - Upstreams + get: + description: Get an Upstream using ID or name in a workspace. + operationId: get-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an Upstream in a workspace + tags: + - Upstreams + patch: + description: Update an Upstream in a workspace + operationId: update-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an Upstream in a workspace + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name in a workspace. + operationId: upsert-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Upstream in a workspace + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/upstream_id_or_name' + '/{workspace}/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: A successful response listing Targets + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Targets associated with an Upstream in a workspace + tags: + - Targets + operationId: list-targets-with-upstream-workspace + post: + description: Create a new Target associated with an Upstream in a workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Target associated with an Upstream in a workspace + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-with-upstream-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/upstream_id_or_name' + '/{workspace}/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target in a workspace. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Target associated with a an Upstream in a workspace + tags: + - Targets + operationId: delete-target-with-upstream-workspace + get: + description: Get a Target associated with an Upstream using ID or target in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream in a workspace + tags: + - Targets + operationId: fetch-target-with-upstream-workspace + patch: + description: Update a Target associated with a an Upstream using ID or target in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Target associated with a an Upstream in a workspace + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-with-upstream-workspace + put: + description: Create or Update a Target associated with an Upstream using ID or target in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Target associated with an Upstream in a workspace + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-with-upstream-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + '/{workspace}/vaults': + get: + description: List all Vaults in a workspace + operationId: list-vault-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Vaults in a workspace + tags: + - Vaults + post: + description: Create a new Vault in a workspace + operationId: create-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Vault in a workspace + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault in a workspace + operationId: delete-vault-in-workspace + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + summary: Delete a Vault in a workspace + tags: + - Vaults + get: + description: Get a Vault using ID or prefix in a workspace. + operationId: get-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Vault in a workspace + tags: + - Vaults + patch: + description: Update a Vault in a workspace + operationId: update-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Vault in a workspace + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix in a workspace. + operationId: upsert-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Vault in a workspace + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/vault_id_or_prefix' + /consumer_groups: + get: + summary: List consumer groups + tags: + - consumer_groups + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups + description: | + List all consumer groups + + Use consumer groups to manage consumer affiliation. + post: + summary: Create a consumer group + operationId: post-consumer_groups + responses: + '201': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a new consumer group. + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List a specific consumer group + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups-group_name + description: Returns a consumer group by passing either the `group_name` or `group_id` as a path parameter. + tags: + - consumer_groups + put: + summary: Create consumer group + operationId: put-consumer_groups-group_name_or_id + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a consumer group by passing a new group name as the path parameter + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + delete: + summary: Delete a consumer group + operationId: delete-consumer_groups-group_name_or_id + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a consumer group. Deleting a consumer group removes all consumers from that group. This operation does not delete existing consuemrs. + tags: + - consumer_groups + '/consumers/{consumer_username_or_id}/consumer_groups': + parameters: + - $ref: '#/components/parameters/Gatewayapi_Consumer_username_or_id' + get: + summary: List consumer groups for a consumer + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumers-consumer_name_or_id-consumer_groups + description: | + View all consumer groups that a consumer is assigned to. + tags: + - consumer_groups + parameters: + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-size' + post: + summary: Add a consumer to a specific consumer group. + operationId: post-consumers-consumer_username_or_id-consumer_groups + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + requestBody: + content: + application/json: + schema: + type: object + properties: + group: + type: string + description: | + The name or ID of the group to add the consumer to. + example: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + required: + - group + examples: + Example request body: + value: + group: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + description: The request body contains the group ID for the group that you are adding a consumer into. + tags: + - consumer_groups + delete: + summary: Remove a consumer from all groups + operationId: delete-consumers-consumer_username_or_id-consumer_groups + responses: + '204': + description: | + HTTP/1.1 204 No Content + description: Remove a consumer from all groups. + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}/consumers': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List all consumers in a consumer group + tags: + - consumer_groups + operationId: get-consumer_groups-group_name_or_id-consumers + description: List all consumers in a consumer group + parameters: + - $ref: '#/components/parameters/Gatewayapi_Pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + post: + summary: Add a consumer to a group + operationId: post-consumer_groups-group_name_or_id-consumers + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + tags: + - consumer_groups + requestBody: + content: + application/json: + schema: + type: object + properties: + consumer: + type: string + description: | + The name or ID of the consumer to add to this group. + example: 8a4bba3c-7f82-45f0-8121-ed4d2847c4a4 + delete: + summary: Remove all consumers from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes all consumers from a specified consumer group. + tags: + - consumer_groups + '/consumers/{consumer_name_or_id}/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/consumer_name_or_id' + - $ref: '#/components/parameters/group_name_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumers-consumer_name_or_id-consumer_groups-group_name_or_id + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes a consumer from a consumer group. This operation does not delete the consumer group. + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}/consumers/{consumer_username_or_id}': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + - $ref: '#/components/parameters/consumer_username_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers-consumer_name_or_id + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: The consumer groups endpoint for removing a consumer from a specified consumer group. + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}/overrides/plugins/rate-limiting-advanced': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + put: + summary: Configure rate limiting for a consumer group. + operationId: put-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + x-examples: + Example 1: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + properties: + config: + type: object + properties: + limit: + type: array + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + retry_after_jitter_max: + type: integer + description: | + The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + window_size: + type: array + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + example: sliding + group: + type: string + description: The consumer group + example: test-group + plugin: + type: string + description: The name of the plugin + example: rate-limiting-advanced + examples: + 'Example ': + value: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + description: | + Define custom rate limiting settings for a consumer group. This endpoint overrides the settings of the Rate Limiting Advanced plugin. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + '401': + $ref: '#/components/responses/HTTP401Error' + requestBody: + content: + application/json: + schema: + type: object + properties: + config.limit: + type: string + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + config.window_size: + type: string + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + example: ' 10' + config.window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + default: sliding + enum: + - sliding + - fixed + config.retry_after_jitter_max: + type: string + description: The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + required: + - config.limit + - config.window_size + examples: + Request body: + value: + config.limit: string + config.window_size: ' 10' + config.window_type: sliding + config.retry_after_jitter_max: string + description: | + Request Body + tags: + - consumer_groups + delete: + summary: Delete the configurations for a consumer group + operationId: delete-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete custom rate limiting settings for a consumer group. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + tags: + - consumer_groups + '/consumer_groups/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer group. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a consumer group + tags: + - Plugins + operationId: list-plugins-consumer-group + post: + description: Create a new plugin associated with a Consumer Group + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a consumer group + tags: + - Plugins + operationId: create-plugin-for-consumer-group + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumer_groups/{consumer_group_name_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a a consumer group using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a consumer group + tags: + - Plugins + operationId: delete-plugin-for-consumer-group + get: + description: Get a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Not Found + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: Not found + properties: + message: + type: string + example: Not Found + description: 404 Not Found + examples: + Not Found: + value: + message: Not Found + summary: Fetch a plugin associated with a Consumer Group + tags: + - Plugins + operationId: fetch-plugin-with-consumer-group + patch: + description: Update a plugin associated with a consumer group using the consumergroup name or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a consumer group + tags: + - Plugins + operationId: update-plugin-with-consumer-group + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer Group + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-customer-group + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_group_name_or_id' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/consumer_groups': + parameters: + - $ref: '#/components/parameters/workspace' + get: + summary: List consumer groups + tags: + - consumer_groups + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups_with_workspace + description: | + List all consumer groups + + Use consumer groups to manage consumer affiliation. + post: + summary: Create a consumer group + operationId: post-consumer_groups_with_workspace + responses: + '201': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a new consumer group. + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List a specific consumer group + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups-group_name_with_workspace + description: Returns a consumer group by passing either the `group_name` or `group_id` as a path parameter. + tags: + - consumer_groups + put: + summary: Create consumer group + operationId: put-consumer_groups-group_name_or_id_with_workspace + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a consumer group by passing a new group name as the path parameter + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + delete: + summary: Delete a consumer group + operationId: delete-consumer_groups-group_name_or_id_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a consumer group. Deleting a consumer group removes all consumers from that group. This operation does not delete existing consuemrs. + tags: + - consumer_groups + '/{workspace}/consumers/{consumer_username_or_id}/consumer_groups': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/Gatewayapi_Consumer_username_or_id' + get: + summary: List consumer groups for a consumer + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumers-consumer_name_or_id-consumer_groups_with_workspace + description: | + View all consumer groups that a consumer is assigned to. + tags: + - consumer_groups + parameters: + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-size' + post: + summary: Add a consumer to a specific consumer group. + operationId: post-consumers-consumer_username_or_id-consumer_groups_with_workspace + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + requestBody: + content: + application/json: + schema: + type: object + properties: + group: + type: string + description: | + The name or ID of the group to add the consumer to. + example: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + required: + - group + examples: + Example request body: + value: + group: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + description: The request body contains the group ID for the group that you are adding a consumer into. + tags: + - consumer_groups + delete: + summary: Remove a consumer from all groups + operationId: delete-consumers-consumer_username_or_id-consumer_groups_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + description: Remove a consumer from all groups. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}/consumers': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List all consumers in a consumer group + tags: + - consumer_groups + operationId: get-consumer_groups-group_name_or_id-consumers_with_workspace + description: List all consumers in a consumer group + parameters: + - $ref: '#/components/parameters/Gatewayapi_Pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + post: + summary: Add a consumer to a group + operationId: post-consumer_groups-group_name_or_id-consumers_with_workspace + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + tags: + - consumer_groups + requestBody: + content: + application/json: + schema: + type: object + properties: + consumer: + type: string + description: | + The name or ID of the consumer to add to this group. + example: 8a4bba3c-7f82-45f0-8121-ed4d2847c4a4 + delete: + summary: Remove all consumers from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes all consumers from a specified consumer group. + tags: + - consumer_groups + '/{workspace}/consumers/{consumer_name_or_id}/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_name_or_id' + - $ref: '#/components/parameters/group_name_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumers-consumer_name_or_id-consumer_groups-group_name_or_id_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes a consumer from a consumer group. This operation does not delete the consumer group. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}/consumers/{consumer_username_or_id}': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + - $ref: '#/components/parameters/consumer_username_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers-consumer_name_or_id_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: The consumer groups endpoint for removing a consumer from a specified consumer group. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}/overrides/plugins/rate-limiting-advanced': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + put: + summary: Configure rate limiting for a consumer group. + operationId: put-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced_with_workspace + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + x-examples: + Example 1: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + properties: + config: + type: object + properties: + limit: + type: array + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + retry_after_jitter_max: + type: integer + description: | + The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + window_size: + type: array + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + example: sliding + group: + type: string + description: The consumer group + example: test-group + plugin: + type: string + description: The name of the plugin + example: rate-limiting-advanced + examples: + 'Example ': + value: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + description: | + Define custom rate limiting settings for a consumer group. This endpoint overrides the settings of the Rate Limiting Advanced plugin. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + '401': + $ref: '#/components/responses/HTTP401Error' + requestBody: + content: + application/json: + schema: + type: object + properties: + config.limit: + type: string + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + config.window_size: + type: string + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + example: ' 10' + config.window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + default: sliding + enum: + - sliding + - fixed + config.retry_after_jitter_max: + type: string + description: The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + required: + - config.limit + - config.window_size + examples: + Request body: + value: + config.limit: string + config.window_size: ' 10' + config.window_type: sliding + config.retry_after_jitter_max: string + description: | + Request Body + tags: + - consumer_groups + delete: + summary: Delete the configurations for a consumer group + operationId: delete-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete custom rate limiting settings for a consumer group. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer group. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a consumer group + tags: + - Plugins + operationId: list-plugins-consumer-group_with_workspace + post: + description: Create a new plugin associated with a Consumer Group + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a consumer group + tags: + - Plugins + operationId: create-plugin-for-consumer-group_with_workspace + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + '/{workspace}/consumer_groups/{consumer_group_name_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a a consumer group using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a consumer group + tags: + - Plugins + operationId: delete-plugin-for-consumer-group_with_workspace + get: + description: Get a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Not Found + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: Not found + properties: + message: + type: string + example: Not Found + description: 404 Not Found + examples: + Not Found: + value: + message: Not Found + summary: Fetch a plugin associated with a Consumer Group + tags: + - Plugins + operationId: fetch-plugin-with-consumer-group_with_workspace + patch: + description: Update a plugin associated with a consumer group using the consumergroup name or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a consumer group + tags: + - Plugins + operationId: update-plugin-with-consumer-group_with_workspace + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer Group + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-customer-group_with_workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_group_name_or_id' + - $ref: '#/components/parameters/plugin_id' + /licenses: + get: + summary: List licenses + tags: + - licenses + responses: + '200': + $ref: '#/components/responses/license-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-licenses + description: | + List active licenses. The data planes use the most recent updated_at license. + post: + summary: Add a license + operationId: post-licenses + responses: + '201': + $ref: '#/components/responses/license-response' + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Create a license using an auto-generated UUID. When using `POST`, if the request payload does contain a valid Kong Gateway license, the license will be added. + + If the request payload does not contain a valid licence, a `400 BAD REQUEST` will be returned. + requestBody: + $ref: '#/components/requestBodies/license-request' + tags: + - licenses + '/licenses/{license-id}': + parameters: + - $ref: '#/components/parameters/license-id' + get: + summary: List a specific license + responses: + '200': + $ref: '#/components/responses/license-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-licenses-license-id + description: List a specific license using the license id parameter. + tags: + - licenses + put: + summary: Update or add a license + operationId: put-licenses-license-id + responses: + '200': + $ref: '#/components/responses/license-response' + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + '405': + description: Method Not Allowed + description: |- + When using `PUT`, if the request payload does not contain an entity's primary key (`id` for licenses), the license will be added and assigned the given ID. + + If the request payload does contain an entity's primary key (id for Licenses), the license will be replaced with the given payload attribute. If the ID is not a valid UUID, a `400 BAD REQUEST` will be returned. If the ID is omitted, a `405 NOT ALLOWED` will be returned. + requestBody: + $ref: '#/components/requestBodies/license-request' + tags: + - licenses + patch: + summary: Update a license + operationId: patch-licenses-license-id + responses: + '200': + $ref: '#/components/responses/license-response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + When using `PATCH`, if the request payload does contain an entity's primary key (`id` for licenses), the license will be replaced with the given payload attribute. + + If the request payload does not contain an entity's primary key (`id` for licenses), a `404 NOT FOUND `will be returned or if the request payload contains a invalid licence, a `400 BAD REQUEST` will be returned. + requestBody: + $ref: '#/components/requestBodies/license-request' + tags: + - licenses + delete: + summary: Delete a license + operationId: delete-licenses-license-id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete a license by passing the license ID as a path parameter. + tags: + - licenses + /license/report: + get: + summary: Generate a report + tags: + - licenses + responses: + '200': + $ref: '#/components/responses/report-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-license-report + description: | + Generate a report on the Kong Gateway instance to gather monthly usage data. + /keyring: + get: + summary: Fetch cluster Keyring + tags: + - Keyring + responses: + '200': + $ref: '#/components/responses/key-ring-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-keyring + description: Kong Gateway provides a mechanism to store sensitive data fields, such as consumer secrets, in an encrypted format within the database.This provides for encryption-at-rest security controls in a Kong cluster. For more information review the [keyring and data encryption documentation](https://docs.konghq.com/gateway/latest/kong-enterprise/db-encryption/#getting-started). + /endpoints: + get: + summary: List all endpoints + tags: + - Information + responses: + '200': + $ref: '#/components/responses/get-endpoints' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-endpoints + description: List all available endpoints provided by the Admin API. + '/{endpoint}': + parameters: + - schema: + type: string + example: key + name: endpoint + in: path + required: true + description: Any available endpoint + head: + summary: Check endpoint or entity existence + operationId: head-endpoints + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:38:29 GMT' + Content-Type: + description: The media type of the message content + schema: + type: string + example: text/html; charset=UTF-8 + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: aqETeVmkeiGnAMzdUT2JRWroB2myY1lB + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '404': + description: Endpoint does not exist + headers: {} + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Similar to `HTTP` GET, but does not return the body. Returns HTTP 200 when the endpoint exits or HTTP 404 when it does not. Other status codes are possible. + tags: + - Information + options: + summary: List method by endpoint + operationId: options-endpoint + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:24:17 GMT' + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + Access-Control-Allow-Headers: + description: Used in response to a preflight request to indicate which HTTP headers can be used during the actual request + schema: + type: string + example: 'Content-Type, Kong-Admin-Token, Kong-Request-Type, Cache-Control' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: gDP1cF3OsNbrgcKPhRNE0RXRNfS7NcoG + Allow: + description: Lists the HTTP methods that are supported for the resource + schema: + type: string + example: 'OPTIONS, PATCH, POST' + Access-Control-Allow-Methods: + description: Indicates the methods allowed when accessing the resource in response to a preflight request + schema: + type: string + example: 'OPTIONS, PATCH, POST' + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request. + tags: + - Information + '/schemas/{entity}/validate': + parameters: + - schema: + type: string + name: entity + in: path + required: true + get: + summary: Retrieve entity schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + - id: + auto: true + type: string + uuid: true + properties: + fields: + type: array + description: A value of a schema + items: + type: object + properties: + id: + type: object + description: A value of a schema + properties: + auto: + type: boolean + description: A value of a schema + type: + type: string + description: A value of a schema + uuid: + type: boolean + description: A value of a schema + examples: + A mock schema: + value: + fields: + - id: + auto: true + type: string + uuid: true + - created_at: + auto: true + timestamp: true + type: integer + operationId: get-schemas-entity + description: Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations with Kong. + post: + summary: Validate a configuration against a schema + operationId: post-schemas-entity-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + Message: + type: string + example: schema validation successful + description: A success message + examples: + schema validation successful: + value: + Message: schema validation successful + description: |- + Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Information + + '/schemas/plugins/{plugin_name}': + parameters: + - schema: + type: string + example: basic-auth + name: plugin_name + in: path + required: true + description: The name of a Kong plugin + get: + summary: Retrieve Plugin Schema + tags: + - Information + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-plugins-plugin_name + description: | + Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system. + /schemas/plugins/validate: + post: + summary: Validate plugin schema + operationId: post-schemas-plugins-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: schema validation successful + properties: + message: + type: string + description: A successful message + example: schema validation successful + examples: + schema validation successful: + value: + message: schema validation successful + description: |- + Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + + This only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Information + /timers: + get: + summary: Retrieve Runtime Debugging Info of Kong's Timers + tags: + - Information + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + stats: + sys: + total: 13 + waiting: 12 + runs: 6771 + pending: 0 + running: 1 + flamegraph: + pending: '' + running: '' + elapsed_time: '' + timers: + router-rebuild: + is_running: false + name: router-rebuild + stats: + runs: 464 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 464 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off': + is_running: false + name: 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off' + stats: + runs: 3 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 3 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + worker: + id: 0 + count: 5 + properties: + stats: + type: object + description: Statistics about the worker + properties: + sys: + type: object + description: List of the number of different type of timers + properties: + total: + description: The total number of timers (running + pending + waiting) + type: integer + default: 7 + example: 7 + waiting: + description: The number of unexpired timers + type: integer + default: 7 + example: 7 + runs: + description: The total number of runs for the timers + type: integer + default: 7 + example: 7 + pending: + description: The number of pending timers + type: integer + default: 0 + example: 0 + running: + description: The number of running timers + type: integer + default: 0 + example: 0 + flamegraph: + type: object + description: String-encoded timer-related flamegraph data + properties: + pending: + description: The number of pending timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + running: + description: The number of running timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + elapsed_time: + description: The elapsed time for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17 + timers: + description: Timer statistics for the worker + type: object + properties: + meta: + description: Program callstack of created timers + type: object + properties: + name: + description: The name of the timer's metadata + type: string + example: '@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()' + worker: + type: object + properties: + id: + type: integer + description: The ordinal number of the current Nginx worker processes (starting from number 0). + count: + type: integer + description: The total number of the Nginx worker processes. + operationId: get-timers + description: Retrieve runtime stats data from [lua-resty-timer-ng](https://github.com/Kong/lua-resty-timer-ng). + + /status: + get: + summary: Health Routes + tags: + - Information + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_workspaces: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_keyring: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + properties: + memory: + type: object + description: Metrics about the memory usage. + properties: + lua_shared_dicts: + type: object + description: An array of dictionary objects that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (`capacity`) and how much of said memory is in use (`allocated_slabs`). + properties: + kong_core_db_cache: + type: object + properties: + capacity: + type: string + example: 128.00 MiB + description: Memory capacity + allocated_slabs: + type: string + example: 128.00 MiB + description: Total allocated memory + workers_lua_vms: + type: array + description: An array with all workers of the Kong node, each entry contains a `http_allocated_gc` string and a `pid`. + items: + type: object + properties: + http_allocated_gc: + type: string + description: | + HTTP submodule's Lua virtual machine's memory usage information. + pid: + type: integer + description: A worker's process identification number. + example: 18478 + database: + type: object + description: Metrics about the database + properties: + reachable: + type: boolean + description: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself. + server: + type: object + description: Metrics about the nginx HTTP/S server + properties: + connections_reading: + type: integer + description: The current number of connections where Kong is reading the request header. + example: 3 + connections_writing: + type: integer + description: The current number of connections where nginx is writing the response back to the client. + example: 1 + total_requests: + type: integer + description: The total number of client requests. + example: 1 + connections_waiting: + type: integer + description: The current number of idle client connections waiting for a request. + example: 1 + connections_handled: + type: integer + description: The total number of handled connections. Generally, the parameter value is the same as the `connections_accepted` parameter unless some resource limits have been reached. + example: 1 + connections_active: + type: integer + description: The current number of active client connections including waiting connections. + example: 1 + connections_accepted: + type: integer + description: The total number of accepted client connections. + example: 1 + examples: + Status endpoint response: + value: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_workspaces: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_keyring: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + operationId: get-status + description: |- + Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, the status of the database connection, and node's memory usage. + + `status_listen` listens on port `8007` by default, however `8001` can be used for status checks as well. The status endpoint provides detailed metrics regarding memory usage, worker process stats, database connection status, and server connection metrics. + + If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used. + + /status/dns: + get: + summary: DNS Status + tags: + - Information + operationId: getDnsStatus + description: | + Retrieve DNS worker and stats information. If the legacy DNS client is in use, it returns a 501 status with a message. + responses: + '200': + description: DNS worker and stats information + content: + application/json: + schema: + type: object + properties: + worker: + type: object + description: Worker information. + properties: + id: + type: integer + description: The worker ID. + example: 1 + count: + type: integer + description: The total number of workers. + example: 4 + stats: + type: object + description: DNS stats information (specific details depend on the Kong instance). + '501': + description: Legacy DNS client in use + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Message indicating that the endpoint is not implemented with the legacy DNS client. + example: "not implemented with the legacy DNS client" + '401': + $ref: '#/components/responses/HTTP401Error' + /keyring/generate: + post: + summary: Generate key + operationId: post-keyring-generate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + properties: + key: + type: string + description: Key material + example: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: + type: string + description: The key's ID + example: 8zgITLQh + description: |- + Generate key material. + + Kong supports rotating keys by allowing for multiple keys to exist on the keyring at the same time. This allows for data fields written by one key to be read back, while a fresher encryption key is used for write operations. Rotating keys is a matter of importing or generating a new key into the keyring, and marking it as active. + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Keyring + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + properties: + key: + type: string + example: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: + type: string + example: 8zgITLQh + examples: + Example 1: + value: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + /keyring/activate: + post: + summary: Activate key + operationId: post-keyring-activate + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Kong can write new sensitive data fields with the current active key, and read previously written fields in the database with the prior key, provided that key is in the keyring. Kong automatically selects the appropriate key to use when decrypting fields from the database. + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: 3Rwvk223 + properties: + key: + type: string + description: The key ID + example: 3Rwvk223 + description: The request body contains a key ID that can be generated from the `/keyring/generate` endpoint. + tags: + - Keyring + /keyring/recover: + post: + summary: Recover keyring + operationId: post-keyring-recover + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: successfully recovered 1 keys + recovered: + - RfsDJ2Ol + not_recovered: + - xSD219lH + properties: + message: + type: string + description: A message containing details about your request. + example: successfully recovered 1 keys + recovered: + type: array + items: + type: string + example: RfsDJ2Ol + not_recovered: + type: array + items: + type: string + example: xSD219lH + examples: + example: + value: + message: successfully recovered 1 keys + recovered: + - RfsDJ2Ol + not_recovered: + - xSD219lH + description: | + The keyring material is then encrypted with the public RSA key defined with the `keyring_recovery_public_key` Kong configuration value in the database. The corresponding private key can be used to decrypt the keyring material in the database. + + The response contains a list of keys that were successfully recovered and that could not be recovered. The Kong error log will contain the detailed reason why the keys could not be recovered. + requestBody: + description: |- + The request body contains a single file named `recovery_private_key` that represents a private RSA key used for decrypting a keyring material stored in the database. + + The private key is uploaded in the PEM format, which is a binary format used for storing cryptographic keys and certificates. The contents of the file are encoded as a string using a specified encoding (such as base64) and included in the request body + content: + multipart/form-data: + schema: + type: object + properties: + recovery_private_key: + type: string + format: binary + example: /path/to/generated/ + description: Private key in PEM format. + examples: + Example 1: + value: + recovery_private_key: /path/to/generated/ + tags: + - Keyring + /keyring/remove: + post: + summary: Remove key + operationId: post-keyring-remove + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Remove a key from the keyring. + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: 3Rwvk223 + properties: + key: + type: string + description: The key ID + example: 3Rwvk223 + description: The request body contains a key ID that can be generated from the `/keyring/generate` endpoint. + tags: + - Keyring + /keyring/export: + post: + summary: Export keyring + operationId: post-keyring-export + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: eyJrIjoIn0= + description: opaque blob containing a keyring. + properties: + data: + type: string + example: eyJrIjoiV1JZeTdubDlYeFZpR3VVQWtWTXBcL0JiVW1jMWZrWHluc0dKd + examples: + Example: + value: + data: eyJrIjoiV1JZeTdubDlYeFZpR3VVQWtWTXBcL0JiVW1jMWZrWHluc0dKd + description: | + Export the keyring. The exported material can be re-imported to the cluster in the event of an outage or to restore a previously-deleted key. + The exported keyring should be stored in a safe location for disaster recovery purposes. It is not designed to be modified or decrypted before being used during a disaster recovery process. + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Keyring + /tags: + get: + summary: List all tags + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags + description: |- + Returns a paginated list of all the tags in the system. + + The list of entities isn't restricted to a single entity type. All the entities tagged with tags are present in this list. + + If an entity is tagged with more than one tag, the `entity_id` for that entity appears more than once in the resulting list. Similarly, if several entities have been tagged with the same tag, the tag appears in several items of this list. + '/tags/{tags}': + parameters: + - $ref: '#/components/parameters/tag' + get: + summary: List entity by tag + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags-tags + description: |- + Returns the entities that have been tagged with the specified tag. + + The list of entities isn't restricted to a single entity type. All the entities tagged with tags are present in this list. + /keyring/import: + post: + summary: Import Keyring + operationId: post-keyring-import + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + created_at: 1576518704 + consumer: + id: 6375b5fd-9c95-4822-b2dd-80ffbccb7ec9 + id: fc46ce48-c1d6-4078-9f51-5a777350a8a2 + password: da61c0083b6d19ef3db2490d0da96a71572da0fa + username: bob + properties: + created_at: + type: integer + description: Datetime representation of the keyring creation date. + consumer: + type: object + description: The consumer object. + properties: + id: + type: string + example: 6375b5fd-9c95-4822-b2dd-80ffbccb7ec9 + description: ID of the consumer object. + id: + type: string + example: 6375b5fd-9c95-4822-b2dd-80ffbccb7ec9 + description: UUID of the keyring + password: + type: string + example: da61c0083b6d19ef3db2490d0da96a71572da0fa + description: Password associated with the keyring. + username: + type: string + example: user + description: Username associated with the keyring + description: Restart Kong and re-import the previously exported keyring. This operation requires that the keyring_private_key point to the private RSA key associated with the public key used during the initial keyring export. + tags: + - Keyring + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + properties: + key: + type: string + example: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: + type: string + example: 8zgITLQh + examples: + Example 1: + value: {} + description: Import Keyring + '/schemas/vaults/{vault_name}': + parameters: + - schema: + type: string + name: vault_name + in: path + required: true + description: The vault schema to be returned + get: + summary: Retrieve Vault Schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: No vault named + operationId: get-schemas-vaults-vault_name + description: Retrieve the schema of a vault. + post: + summary: Validate Vault Schema + tags: + - Validation + requestBody: + description: Payload containing the schema data to validate + required: true + content: + application/json: + schema: + type: object + properties: + schemaData: + type: string + description: JSON string containing the vault schema data + responses: + '200': + description: Validation successful + content: + application/json: + schema: + type: object + properties: + validation: + type: boolean + description: Indicates if the schema is valid + '400': + description: Bad request due to invalid schema data + '405': + description: Method Not Allowed + operationId: post-schemas-vaults-validate + description: Validates the given vault schema data against predefined validation rules. + /admins: + get: + summary: List Admins + tags: + - admins + responses: + '200': + $ref: '#/components/responses/admins-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-admins + description: Returns a list of admins. To query all admins, add a parameter `all_workspaces=true` to the `/admins` endpoint. The `status` field in the response indicates the state of the admins invitation. `0`= Approved, `1`= Pending, `2`= Rejected, `3`= Revoked, `4` = Invited, `5`= Unverified. + post: + summary: Invite an Admin + operationId: post-admins + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + admin: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + status: + type: integer + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + x-examples: + Example 1: + admin: + created_at: 1556638641 + id: 8f0a742f-07f3-49e0-90d7-4fc7eea7e6a4 + updated_at: 1556638641 + status: 4 + username: test-case-3 + email: test3@test.com + rbac_token_enabled: true + examples: + Example admin response: + value: + admin: + created_at: 0 + id: string + updated_at: 0 + status: 0 + username: string + email: string + rbac_token_enabled: true + '409': + description: Conflict + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Detail about the conflict + example: user already exists with same username, email, or custom_id + x-exmples: + Example 1: + message: user already exists with same username, email, or custom_id + examples: + Constraint violation: + value: + message: user already exists with same username, email, or custom_id + tags: + - admins + description: Invite an admin to your organization. + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + example: email@example.com + description: The admin's email address. + username: + type: string + description: The admin's username + example: myusername + custom_id: + type: string + description: The admin's custom ID + rbac_token_enabled: + type: boolean + description: Allows the admin to use and reset their RBAC token. + default: true + examples: + Invite an admin: + value: + username: test-case-3 + email: test3@test.com + custom_id: customId + rbac_token_enabled: true + /admins/register: + post: + summary: Register an Admin’s Credentials + operationId: post-admins-register + responses: + '201': + description: Created + '401': + $ref: '#/components/responses/HTTP401Error' + description: Register an Admin's Credentials + requestBody: + content: + application/json: + schema: + type: object + properties: + token: + type: string + + username: + type: string + + email: + type: string + + format: email + password: + type: string + + format: password + examples: + Example registration request: + value: + token: string + username: string + email: user@example.com + password: pa$$word + tags: + - admins + /admins/password_resets: + post: + summary: Send a Password Reset Email to an Admin + tags: + - admins + responses: + '201': + description: Created + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-admins-password_resets + description: Using a registered admin's email address issue a password reset email to the admin. + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + + description: The registered admin's email. + example: admin@example.com + examples: + Example reset body: + value: + email: admin@example.com + patch: + summary: Reset an Admin’s Password + operationId: patch-admins-password_resets + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + description: Reset an admin's password. + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + + password: + type: string + + token: + type: string + + examples: + Example 1: + value: + email: string + password: string + token: string + tags: + - admins + '/admins/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The admin’s username or ID. + get: + summary: Retrieve an Admin + tags: + - admins + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + status: + type: integer + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + x-examples: + Example 1: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + status: 4 + username: test-admin + email: test@test.com + rbac_token_enabled: true + examples: + Example response body: + value: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + status: 4 + username: test-admin + email: test@test.com + rbac_token_enabled: true + operationId: get-admins-name_or_id + description: Retrieve an admin using their name or ID. Using `generate_register_url`, you can generate a unique registration URL if the admin's invitation status is `4`. `generate_register_url` overrides the previous registration URL for the particular admin each time it is requested. + patch: + tags: + - admins + summary: Update an Admin + operationId: patch-admins-name_or_id-generate_register_url + responses: + '200': + description: OK + requestBody: + content: + application/json: + schema: + type: object + properties: + name_or_id: + type: string + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + x-examples: + Example 1: + name_or_id: 665b4070-541f-48bf-82c1-53030babaa81 + username: test-renamed + email: test@test.com + rbac_token_enabled: true + examples: + Example 1: + value: + name_or_id: string + username: string + email: string + rbac_token_enabled: true + description: Update information about an admin + delete: + tags: + - admins + summary: Delete an Admin + operationId: delete-admins-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete an admin by specifying the admin's username or ID. + '/admins/{name_or_id}/roles': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The admin’s username or ID + get: + summary: List an Admin’s Roles + tags: + - admins + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + is_default: + type: boolean + x-examples: + Example 1: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + examples: + Example role list: + value: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + operationId: get-admins-name_or_id-roles + description: List all roles related to a registered admin. + post: + summary: Create or Update an Admin’s Roles + operationId: post-admins-name_or_id-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + is_default: + type: boolean + x-examples: + Example 1: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + name: super-admin + is_default: false + examples: + Example role assignment: + value: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + name: super-admin + is_default: false + tags: + - admins + requestBody: + content: + application/json: + schema: + type: object + properties: + roles: + type: string + x-examples: + Example 1: + roles: read-only + description: Comma-separated string of role names to create or update for an admin. + description: Create or update roles for an admin + delete: + tags: + - admins + summary: Delete an Admin’s Role + operationId: delete-admins-name_or_id-roles + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete an admin's roles by passing a comma-separated string of names of specific roles to remove from an admin. + '/admins/{name_or_id}/workspaces': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The admin’s username or ID + get: + summary: List an Admin’s Workspaces + tags: + - admins + responses: + '200': + $ref: '#/components/responses/workspace-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-admins-name_or_id-workspaces + description: Return workspaces associated with an admin. + /groups: + get: + summary: List Groups + tags: + - groups + responses: + '200': + $ref: '#/components/responses/groups-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-groups + description: Returns a list of groups. + post: + summary: Create a new group + operationId: post-groups + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + name: + type: string + comment: + type: string + x-examples: + Example 1: + created_at: 1556638641 + id: 8f0a742f-07f3-49e0-90d7-4fc7eea7e897 + updated_at: 1556638641 + name: demo-group + comment: comment + examples: + Example group response: + value: + created_at: 0 + id: string + updated_at: 0 + name: string + comment: string + tags: + - groups + description: Create a group to your organization. + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The group's name + example: my_group + examples: + Create a group: + value: + name: demo-group + comment: comment + '/groups/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The group’s name or ID. + get: + summary: Retrieve a Group + tags: + - groups + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + name: + type: string + comment: + type: string + x-examples: + Example 1: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + name: test-group + comment: comment1 + examples: + Example response body: + value: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + username: test-group + comment: comment + operationId: get-groups-name_or_id + description: Retrieve a group using their name or ID. + patch: + tags: + - groups + summary: Update a Group + operationId: patch-groups-name_or_id + responses: + '200': + description: OK + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + comment: + type: string + x-examples: + Example 1: + name: test-group + comment: comment1 + examples: + Example 1: + value: + name: string + comment: string + description: Update information about a group + delete: + tags: + - groups + summary: Delete an Group + operationId: delete-groups-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete a group by specifying the group's name or ID. + '/groups/{name_or_id}/roles': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The group’s username or ID + get: + summary: List an Group’s Roles + tags: + - groups + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + group: + type: object + properties: + id: + type: string + name: + type: string + comment: + type: string + updated_at: + type: string + format: date-time + rbac_role: + type: object + properties: + id: + type: string + name: + type: string + workspace: + type: object + properties: + id: + type: string + next: + nullable: true + x-examples: + Example 1: + data: + - group: + comment: 'comment1' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: demo-group + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + examples: + Example role list: + value: + data: + - group: + comment: 'comment1' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: demo-group + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + operationId: get-groups-name_or_id-roles + description: List all roles related to a group. + post: + summary: Create or Update a Group's Roles + operationId: post-groups-name_or_id-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + group: + type: object + properties: + id: + type: string + name: + type: string + comment: + type: string + updated_at: + type: string + format: date-time + rbac_role: + type: object + properties: + id: + type: string + name: + type: string + workspace: + type: object + properties: + id: + type: string + x-examples: + Example 1: + group: + comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + examples: + Example role assignment: + value: + group: + comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + tags: + - groups + requestBody: + content: + application/json: + schema: + type: object + properties: + rbac_role_id: + type: string + workspace_id: + type: string + x-examples: + Example 1: + rbac_role_id: 12773c9a-7f7c-45f2-bcea-5285eb18fd2f + workspace_id: d107bce7-dd86-4124-93c8-667ecc34b32e + description: Comma-separated string of role names to create or update for a group. + description: Create or update roles for a admin + delete: + tags: + - groups + summary: Delete a group’s Role + operationId: delete-groups-name_or_id-roles + parameters: + - name: rbac_role_id + in: query + required: true + schema: + type: string + example: 12773c9a-7f7c-45f2-bcea-5285eb18fd2f + - name: workspace_id + in: query + required: true + schema: + type: string + example: d107bce7-dd86-4124-93c8-667ecc34b32e + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete a group's roles. + '/debug/cluster/control-planes-nodes/log-level/{log_level}': + parameters: + - schema: + type: string + enum: + - debug + - info + - notice + - warn + - error + - crit + name: log_level + in: path + required: true + description: The log level + put: + summary: Set Node Log Level of All Control Plane Nodes + operationId: put-debug-cluster-control-planes-nodes-log-level-log_level + responses: + '200': + description: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Change the log level of all control plane nodes deployed in a hybrid (CP/DP) cluster. + Be careful when changing the log level of a node to debug in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level, such as notice. + It’s currently not possible to change the log level of data plane and DB-less nodes. + + This endpoint can be protected with RBAC, and changes will be reflected in the audit logs. + The log level change is propagated to all Nginx workers of a node, including to newly spawned workers. + + Log levels are set in Kong’s configuration. Possible log levels in increasing order of severity: `debug`, `info`, `notice`, `warn`, `error`, and `crit`. For more information, review the [logging reference](https://docs.konghq.com/gateway/latest/production/logging/). + + When a user dynamically changes the log level for the entire cluster, if a new node joins the cluster, the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. To work around that, make sure the new node starts with the proper level by setting the startup `kong.conf` setting [`KONG_LOG_LEVEL`](https://docs.konghq.com/gateway/latest/reference/configuration/#log_level). + tags: + - debug + '/debug/cluster/log-level/{log_level}': + parameters: + - schema: + type: string + enum: + - debug + - info + - notice + - warn + - error + - crit + name: log_level + in: path + required: true + description: The log level + put: + summary: Set Node Log Level of All Nodes + operationId: put-debug-cluster-log-level-log_level + responses: + '200': + description: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - debug + description: |- + Change the log level of all nodes in a cluster. + + Be careful when changing the log level of a node to debug in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level, such as notice. + It’s currently not possible to change the log level of data plane and DB-less nodes. + + This endpoint can be protected with RBAC, and changes will be reflected in the audit logs. + The log level change is propagated to all Nginx workers of a node, including to newly spawned workers. + + Log levels are set in Kong’s configuration. Possible log levels in increasing order of severity: `debug`, `info`, `notice`, `warn`, `error`, and `crit`. For more information, review the [logging reference](https://docs.konghq.com/gateway/latest/production/logging/). + + Currently, when a user dynamically changes the log level for the entire cluster, if a new node joins the cluster, the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. To work around that, make sure the new node starts with the proper level by setting the startup `kong.conf` setting [`KONG_LOG_LEVEL`](https://docs.konghq.com/gateway/latest/reference/configuration/#log_level). + /debug/node/log-level: + get: + summary: Retrieve Node Log Level of A Node + tags: + - debug + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + message: + type: string + x-examples: + Example 1: + message: 'log level: debug' + examples: + Retrieved debug level: + value: + message: string + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-debug-node-log-level + description: | + Retrieve the current log level of a node. + + See the [Nginx Documentation](https://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + '/debug/node/log-level/{log_level}': + parameters: + - schema: + type: string + enum: + - debug + - info + - notice + - warn + - error + - crit + name: log_level + in: path + required: true + description: The log level + put: + summary: Set Log Level of A Single Node + tags: + - debug + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + message: + type: string + x-examples: + Example 1: + message: log level changed + examples: + Example 1: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-debug-node-log-level-log_level + description: | + Change the log level of a node. + /rbac/users: + get: + summary: List Users + tags: + - RBAC + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-users + description: |- + List all users. + + Note: RBAC users associated with admin aren't listed with `GET /rbac/users`. Instead, use `GET /admins` to list all admins. + post: + summary: Add a User + operationId: post-rbac-users + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + requestBody: + $ref: '#/components/requestBodies/rbac-request' + description: Add a User + '/rbac/users/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC username or UUID. + get: + summary: Retrieve a User + tags: + - RBAC + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-users-name_or_id + description: Retrieve a user by passing a name or ID in the path. + patch: + summary: Update a User + operationId: patch-rbac-users-name_or_id + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + description: Update a user. Users are unable to update their own roles. + requestBody: + $ref: '#/components/requestBodies/rbac-request' + delete: + summary: Delete a User + operationId: delete-rbac-users-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a user. + tags: + - RBAC + /rbac/roles: + get: + summary: List Roles + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + next: + type: string + x-examples: + Example 1: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + examples: + Multiple roles: + value: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + operationId: get-rbac-roles + description: List all roles. + post: + summary: Add a Role + operationId: post-rbac-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + New role response body: + value: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + + description: The RBAC role name. + comment: + type: string + + description: A string describing the RBAC user object. + description: The request body contains the name of the role and an optional attribute. + description: Add a role. + '/rbac/roles/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: Retrieve a Role + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + Example 1: + value: + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id + description: Retrieve a role by passing the name or UUID as a path parameter. + put: + summary: Update or Create a Role + operationId: put-rbac-roles-name_or_id + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: the best + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: doc_lord + examples: + Example entity replacement: + value: + comment: the best + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: doc_lord + '201': + description: Created + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + comment: + type: string + + description: | + With a `PUT` request, if the request payload contains an existing entity’s primary key, the payload replaces the entity specified by the given primary key. If the primary key is not that of an existing entity, the entity is created with the given payload. + patch: + summary: Update a Role + operationId: patch-rbac-roles-name_or_id + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: comment from patch request + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + Patch request response: + value: + comment: comment from patch request + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + attribute: + type: string + + description: | + A string describing the RBAC role object. + description: Attribute request body + description: Updates a role by passing an optional attribute. + delete: + summary: Delete a Role + operationId: delete-rbac-roles-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + description: Delete a role + '/rbac/roles/{name_or_id}/endpoints': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: List Role Endpoints Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + data: + - actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + - actions: + - read + created_at: 1557764438 + endpoint: /services + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-endpoints + description: Lists all of a role's associated endpoint permissions. + post: + summary: Add a Role Endpoint Permission + operationId: post-rbac-roles-name_or_id-endpoints + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + examples: + Basic example: + value: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + tags: + - RBAC + description: |- + Add a role endpoint permission for the path of the associated endpoint. Permissions can be exact matches, or contain wildcards, represented by `*`. + + Exact matches: + - `/services/` + - `/services/foo` + + Wildcards: + - `/services/*` + - `/services/*/plugins` + Where `*` replaces exactly one segment between slashes (or the end of the path). + + Note that wildcards can be nested. For example, `/rbac/*`, `/rbac/*/*`, `/rbac/*/*/*` would refer to all paths under `/rbac/`. +

+ For the `admin` role in the default workspace, CRUD actions on `/groups` and `/groups/*` endpoints are disallowed. + For the `workspace-admin` role in non-default workspaces, CRUD actions on `/groups` and `/groups/*` endpoints are disallowed. + requestBody: + content: + application/json: + schema: + type: object + properties: + workspace: + type: string + + description: Workspace tied to the endpoint. Defaults to the default permission. Using the wildcard `*` means all workspaces are affected. + endpoint: + type: string + + description: | + Endpoint associated with this permission. + negative: + type: string + + description: | + If true, explicitly disallow the actions associated with the permissions tied to this endpoint. By default, this value is false. + actions: + type: string + + description: | + One or more actions associated with this permission, written as a comma-separated string. + For example, `read,create,update,delete`. + comment: + type: string + + description: A string describing the RBAC permission object. + '/rbac/roles/{name_or_id}/endpoints/{workspace_name_or_id}/{endpoint}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + - schema: + type: string + name: workspace_name_or_id + in: path + required: true + description: The workspace name or UUID. + - schema: + type: string + name: endpoint + in: path + required: true + description: The endpoint associated with this permission. + get: + summary: Retrieve a Role Endpoint Permission + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + examples: + basic example: + value: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-endpoints-workspace_name_or_id-endpoint + description: | + Retrieve a Role Endpoint Permission + patch: + summary: Update a Role Endpoint Permission + operationId: patch-rbac-roles-name_or_id-endpoints-workspace_name_or_id-endpoint + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - update + - read + created_at: 1557764438 + endpoint: /services + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + examples: + Example 1: + value: + actions: + - delete + - create + - update + - read + created_at: 1557764438 + endpoint: /services + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + tags: + - RBAC + description: | + Update a Role Endpoint Permission + requestBody: + content: + application/json: + schema: + type: object + properties: + negative: + type: string + + description: | + If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. + actions: + type: string + + description: | + One or more actions associated with this permission. + delete: + summary: Delete a Role Endpoint Permission + operationId: delete-rbac-roles-name_or_id-endpoints-workspace_name_or_id-endpoint + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a Role Endpoint Permission + tags: + - RBAC + '/rbac/roles/{name_or_id}/entities': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: List Entity Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + x-examples: + Example 1: + data: + - actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + Example 1: + value: + data: + - actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-entities + description: | + Add a Role Entity Permission + post: + summary: Add a Role Entity Permission + operationId: post-rbac-roles-name_or_id-entities + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + example response: + value: + actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + tags: + - RBAC + description: The `entity_id` must be the ID of an entity in Kong. If you provide the ID of a workspace, the permission applies to all entities in that workspace. Future entities belonging to that workspace will get the same permissions. A wildcard (`*`) will be interpreted as all entities in the system. + requestBody: + content: + application/json: + schema: + type: object + description: If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. + properties: + negative: + type: string + + description: ID of the entity associated with this permission. + entity_id: + type: string + + description: Type of the entity of a given `entity_id`. + entity_type: + type: string + + description: One or more actions associated with this permission. + actions: + type: string + + description: | + One or more actions associated with this permission. + comment: + type: string + + description: A string describing the RBAC permission object. + description: | + Request Body + '/rbac/roles/{name_or_id}/entities/{entity_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC permission name or UUID. + - schema: + type: string + name: entity_id + in: path + required: true + description: ID of the entity associated with this permission. + get: + summary: Retrieve a Role Entity Permission + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + x-examples: + Example 1: + actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + example-response: + value: + actions: + - string + created_at: 0 + entity_id: string + entity_type: string + negative: true + role: + id: string + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-entities-entity_id + description: | + Retrieve a Role Entity Permission + patch: + summary: Update an Entity Permission + operationId: patch-rbac-roles-name_or_id-entities-entity_id + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + x-examples: + Example 1: + actions: + - update + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + example-response: + value: + actions: + - update + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + description: Update an Entity Permission + requestBody: + content: + application/json: + schema: + type: object + properties: + negative: + type: boolean + + description: | + If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. + actions: + type: string + + description: One or more actions associated with this permission. + delete: + summary: Delete an Entity Permission + operationId: delete-rbac-roles-name_or_id-entities-entity_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete an Entity Permission + tags: + - RBAC + '/rbac/roles/{name_or_id}/permissions': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: List Role Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + endpoints: + type: object + properties: + '*': + type: object + properties: + '*': + type: object + properties: + actions: + type: array + items: + type: string + negative: + type: boolean + /*/rbac/*: + type: object + properties: + actions: + type: array + items: + type: string + negative: + type: boolean + entities: + type: object + properties: {} + x-examples: + Example 1: + endpoints: + '*': + '*': + actions: + - delete + - create + - update + - read + negative: false + /*/rbac/*: + actions: + - delete + - create + - update + - read + negative: true + entities: {} + examples: + role-permission-example: + value: + endpoints: + '*': + '*': + actions: + - delete + - create + - update + - read + negative: false + /*/rbac/*: + actions: + - delete + - create + - update + - read + negative: true + entities: {} + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-permissions + description: List Role Permissions + '/rbac/users/{name_or_id}/roles': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC user name or UUID. + get: + summary: List a User’s Roles + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + user: + type: object + properties: + comment: + type: string + created_at: + type: integer + enabled: + type: boolean + id: + type: string + name: + type: string + user_token: + type: string + user_token_ident: + type: string + x-examples: + Example 1: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557765500 + id: a1c810ee-8366-4654-ba0c-963ffb9ccf2e + name: read-only + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + examples: + Example 1: + value: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557765500 + id: a1c810ee-8366-4654-ba0c-963ffb9ccf2e + name: read-only + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + operationId: get-rbac-users-name_or_id-roles + description: | + Add a User to a Role + post: + summary: Add a User to a Role + operationId: post-rbac-users-name_or_id-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: string + name: + type: string + user: + type: object + properties: + comment: + type: string + created_at: + type: integer + enabled: + type: boolean + id: + type: string + name: + type: string + user_token: + type: string + user_token_ident: + type: string + x-examples: + Example 1: + roles: + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + examples: + example-role-created: + value: + roles: + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Add a User to a Role + requestBody: + content: + application/json: + schema: + type: object + properties: + roles: + type: string + + description: Comma-separated list of role names to assign to the user. + tags: + - RBAC + delete: + summary: Delete a Role from a User + operationId: delete-rbac-users-name_or_id-roles + responses: + '204': + description: No Content + tags: + - RBAC + description: Delete a Role from a User + '/rbac/users/{name_or_id}/permissions': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC user name or UUID. + get: + summary: List a User’s Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + endpoints: + type: object + properties: + '*': + type: object + properties: + '*': + type: object + properties: + actions: + type: array + items: + type: string + negative: + type: boolean + entities: + type: object + properties: {} + x-examples: + Example 1: + endpoints: + '*': + '*': + actions: + - read + negative: false + entities: {} + examples: + Example 1: + value: + endpoints: + '*': + '*': + actions: + - read + negative: false + entities: {} + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-users-name_or_id-permissions + description: | + List a User’s Permissions + /filter-chains: + post: + summary: Add Filter Chain + operationId: post-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Create Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains + operationId: get-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + List All Filter Chains + '/routes/{route_id_or_name}/filter-chains': + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + post: + summary: Add Filter Chain + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_name_or_id-filter-chains + description: | + Create Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Route + operationId: get-routes-route_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + tags: + - filter-chains + description: | + List Filter Chains Associated to a Specific Route + patch: + summary: Update Filter Chain Associated to a Specific Route + operationId: patch-routes-route_id_or_name-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + '/services/{service_id_or_name}/filter-chains': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + post: + summary: Create Filter Chain Associated to a Specific Service + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-services-service_id_or_name-filter-chains + description: | + Add filter chain Associated to a Specific Service + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Service + operationId: get-service_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List Filter Chains Associated to a Specific Service + tags: + - filter-chains + '/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: Retrieve Filter Chain + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + operationId: get-filter-chains-filter_chain_id + description: | + Retrieve Filter Chain + '401': + $ref: '#/components/responses/HTTP401Error' + patch: + summary: Update Filter Chain + operationId: patch-filter-chains-filter_chain_id + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + put: + summary: Update Or Create Filter Chain + operationId: put-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: |- + Inserts (or replaces) the filter chain under the requested resource with the definition specified in the body. The filter chain is identified via the name or ID attribute. + + When the name or ID attribute has the structure of a UUID, the filter chain being inserted or replaced is identified by its ID. Otherwise, it is identified by its name. + + When creating a new filter chain without specifying an ID (neither in the URL nor in the body), the ID will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + delete: + summary: Delete Filter Chain + operationId: delete-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain. + tags: + - filter-chains + '/routes/{route_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: List Filter Chains Associated to a Specific Route + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter-chains-filter_chain_id + description: | + Retrieve filter chain associated to a specific route. + put: + summary: Create Or Update Filter Chain Associated to a Specific Route + operationId: put-routes-route_id_or_name-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Create or update filter chain associated to a specific route. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + tags: + - filter-chains + '/routes/{route_id_or_name}/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + - $ref: '#/components/parameters/route_id_or_name' + delete: + summary: Delete Filter Chain Associated to a Specific Route + tags: + - filter-chains + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter_chain_id + description: | + Delete filter chain associated to a specific route. + '/services/{service_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + delete: + summary: Delete Filter Chain Associated to a Specific Service + operationId: delete-services-service_id_or_name-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain associated to a specific service. + tags: + - filter-chains + /audit/requests: + get: + summary: List request audit logs + parameters: + - $ref: '#/components/parameters/beforeAuditLogFilter' + - $ref: '#/components/parameters/afterAuditLogFilter' + tags: + - audit-logs + responses: + '200': + $ref: '#/components/responses/audit-objects-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-audit-requests + description: |- + You can access request and database audit logs through the Admin API. + The default order of audit log is by request timestamp - latest to oldest. + For usage examples, see [Audit Logging in Kong Gateway](https://docs.konghq.com/gateway/latest/kong-enterprise/audit-log/). + /audit/objects: + get: + summary: List database audit logs + parameters: + - $ref: '#/components/parameters/beforeAuditLogFilter' + - $ref: '#/components/parameters/afterAuditLogFilter' + responses: + '200': + $ref: '#/components/responses/database-audit-log-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-audit-objects + tags: + - audit-logs + description: List database audit logs (ordered by request timestamp - latest to oldest) + /event-hooks: + get: + summary: List all event hooks + tags: + - Event-hooks + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks + description: List all event hooks and return information about the event hooks. + post: + summary: Add a webhook + operationId: post-event-hooks + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Event-hooks + description: | + Add a webhook + requestBody: + $ref: '#/components/requestBodies/add-webhook' + /event-hooks/sources: + get: + summary: List all sources + tags: + - Event-hooks + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + balancer: + type: object + properties: + health: + type: object + properties: + fields: + type: array + items: + type: string + crud: + type: object + properties: + acls: + type: object + properties: + fields: + type: array + items: + type: string + rate-limiting-advanced: + type: object + properties: + rate-limit-exceeded: + type: object + properties: + description: + type: string + fields: + type: array + items: + type: string + unique: + type: array + items: + type: string + x-examples: + Example 1: + data: + balancer: + health: + fields: + - upstream_id + - ip + - port + - hostname + - health + crud: + acls: + fields: + - operation + - entity + - old_entity + - schema + rate-limiting-advanced: + rate-limit-exceeded: + description: Run an event when a rate limit has been exceeded + fields: + - consumer + - ip + - service + - rate + - limit + - window + unique: + - consumer + - ip + - service + examples: + sources example: + value: + data: + balancer: + health: + fields: + - string + crud: + acls: + fields: + - string + rate-limiting-advanced: + rate-limit-exceeded: + description: string + fields: + - string + unique: + - string + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks-sources + description: | + Sources are the actions that trigger the event hook. The `/sources` JSON output follows the following pattern: + + * 1st level = The source, which is the action that triggers the event hook. + * 2nd level = The event, which is the Kong entity the event hook listens to for events. + * 3rd level = The available template parameters for use in `webhook-custom` payloads. + + For instance, in the example below `balancer` is the source, `health` is the event, and `upstream_id`, `ip`, `port`, `hostname`, and `health` are the available template parameters. + '/event-hooks/sources/{source}': + parameters: + - schema: + type: string + name: source + in: path + required: true + description: The source you want to list events from. + get: + summary: List all events for a source + tags: + - Event-hooks + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + create: + type: object + properties: + fields: + type: array + items: + type: string + delete: + type: object + properties: + fields: + type: array + items: + type: string + update: + type: object + properties: + fields: + type: array + items: + type: string + x-examples: + Example 1: + data: + create: + fields: + - operation + - entity + - old_entity + - schema + delete: + fields: + - operation + - entity + - old_entity + - schema + update: + fields: + - operation + - entity + - old_entity + - schema + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks-sources-source + description: Events are the Kong entities the event hook listens for events. With this endpoint, you can list all of the events associated with a particular source. + '/event-hooks/{event-hook-id}/test': + parameters: + - schema: + type: string + name: event-hook-id + in: path + required: true + description: The event hook id + post: + summary: Test an event hook + operationId: post-event-hooks-event-hook-id-test + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + It’s useful to manually trigger an event hook without provoking the event to be triggered. For instance, you might want to test the integration, or see if your hook’s service is receiving a payload from Kong. + + POST any data to `/event-hooks/:id-of-hook/test`, and the `/test` endpoint executes the with the provided data as the event payload. + tags: + - Event-hooks + '/event-hooks/{event-hook-id}': + delete: + summary: Delete an event hook + description: Deletes a specific event hook by its ID. + operationId: deleteEventHook + parameters: + - name: event-hook-id + in: path + required: true + description: The ID of the event hook to delete. + schema: + type: string + responses: + '204': + description: Event hook successfully deleted. + '404': + description: Event hook not found. + tags: + - Event-hooks + '/event-hooks/{event-hook-id}/ping': + get: + summary: Ping a webhook event hook + parameters: + - name: event-hook-id + in: path + required: true + description: The ID of the event hook to delete. + schema: + type: string + tags: + - Event-hooks + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks-event-hook-id-ping + description: | + Ping a webhook event hook. + '/{workspace}/rbac/roles': + parameters: + - schema: + type: string + name: workspace + in: path + required: true + description: The workspace name or UUID. + get: + summary: List roles for a workspace + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + next: + type: string + x-examples: + Example 1: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + examples: + Multiple roles: + value: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + operationId: get-rbac-roles-by-workspace + description: List all roles by workspace + post: + summary: Add a role + operationId: post-rbac-roles-workspace + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + New role response body: + value: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + + description: The RBAC role name. + comment: + type: string + + description: A string describing the RBAC user object. + description: The request body contains the name of the role and an optional attribute. + description: Add a role. + '/{workspace}/rbac/roles/{role}/endpoints/{endpoint}/': + get: + summary: Get role-specific permissions for an endpoint within a workspace + parameters: + - in: path + name: workspace + required: true + schema: + type: string + description: The workspace name or UUID. + - in: path + name: role + required: true + schema: + type: string + description: The RBAC role ID. + - in: path + name: endpoint + required: true + schema: + type: string + description: The specific endpoint to retrieve permissions for. + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + example: + actions: + - "delete" + - "create" + - "update" + - "read" + created_at: 1557764505 + endpoint: "/consumers" + negative: false + role: + id: "23df9f20-e7cc-4da4-bc89-d3a08f976e50" + workspace: "default" + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: getRoleSpecificEndpointPermissions + tags: + - RBAC + + '/fips-status': + get: + summary: FIPS Mode Status + tags: + - licenses + description: >- + Retrieves the current FIPS mode status. This endpoint indicates whether FIPS mode is active and provides the version of the FIPS module. + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + 200: + description: FIPS mode status retrieved successfully. + content: + application/json: + schema: + type: object + properties: + active: + type: boolean + description: Indicates if FIPS mode is currently active (true) or inactive (false). + version: + type: string + description: The version of the FIPS module, or 'unknown' if the version cannot be determined. + examples: + fips_enabled: + value: {"active": true, "version": "2.0.16"} + summary: FIPS mode is enabled. This may occur after a license configuration change that enables FIPS mode. + fips_disabled: + value: {"active": false, "version": "unknown"} + summary: FIPS mode is disabled or not supported. This may be the default state or result from a license configuration that does not enable FIPS mode. + '/workspace_/groups': + get: + operationId: list-groups + responses: + "200": + content: + application/json: + schema: + items: + properties: + created_at: + format: date-time + type: string + id: + type: string + name: + type: string + type: object + type: array + description: Successfully retrieved the list of groups + summary: Retrieve a list of all groups + tags: + - Workspaces + post: + operationId: create-group + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + required: + - name + type: object + responses: + "201": + content: + application/json: + schema: + properties: + created_at: + format: date-time + type: string + id: + type: string + name: + type: string + type: object + description: Successfully created the group + summary: Create a new group + tags: + - Workspaces + '/workspace_/groups/{groups}': + parameters: + - in: path + name: groups + required: true + schema: + type: string + patch: + operationId: update-group + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + type: object + responses: + "200": + description: Successfully updated the group + summary: Update details of a specific group + tags: + - Workspaces + '/workspace_/groups/{groups}/roles': + delete: + operationId: remove-role-from-group + parameters: + - in: query + name: rbac_role_id + required: true + schema: + type: string + - in: query + name: workspace_id + required: true + schema: + type: string + responses: + "204": + description: Successfully removed the role association + summary: Remove a role association from a group + tags: + - Workspaces + get: + operationId: list-group-roles + responses: + "200": + content: + application/json: + schema: + items: + properties: + group: + properties: + id: + type: string + name: + type: string + type: object + rbac_role: + properties: + id: + type: string + name: + type: string + type: object + workspace: + properties: + id: + type: string + type: object + type: object + type: array + description: Successfully retrieved the roles + summary: Retrieve roles associated with a specific group + tags: + - Workspaces + parameters: + - in: path + name: groups + required: true + schema: + type: string + post: + operationId: add-role-to-group + requestBody: + content: + application/json: + schema: + properties: + rbac_role_id: + type: string + workspace_id: + type: string + required: + - rbac_role_id + - workspace_id + type: object + responses: + "201": + content: + application/json: + schema: + properties: + group: + properties: + id: + type: string + name: + type: string + type: object + rbac_role: + properties: + id: + type: string + name: + type: string + type: object + workspace: + properties: + id: + type: string + type: object + type: object + description: Successfully associated the role with the group + summary: Associate a role with a group + tags: + - Workspaces + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong Gatewat is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong Gatewat is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache + +servers: + - description: Default Admin API URL + url: '{protocol}://{hostname}:{port}{path}' + variables: + hostname: + default: localhost + description: Hostname for Kong's Admin API + path: + default: / + description: Base path for Kong's Admin API + port: + default: '8001' + description: Port for Kong's Admin API + protocol: + default: http + description: Protocol for requests to Kong's Admin API + enum: + - http + - https +security: + - kongAdminToken: [] +tags: + - description: | + Service entities are abstractions of your microservice interfaces or formal APIs. For example, a service could be a data transformation microservice or a billing API. +

+ The main attribute of a service is the destination URL for proxying traffic. This URL can be set as a single string or by specifying its protocol, host, port and path individually. +

+ Services are associated to routes, and a single service can have many routes associated with it. Routes are entrypoints in Kong Gateway which define rules to match client requests. Once a route is matched, Kong Gateway proxies the request to its associated service. See the [Proxy Reference](https://docs.konghq.com/gateway/latest/how-kong-works/routing-traffic/) for a detailed explanation of how Kong proxies traffic. +

+ Services can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). + name: Services + - description: | + Route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to the associated service. You need at least one matching rule that applies to the protocol being matched by the route. +

+ The combination of routes and services, and the separation of concerns between them, offers a powerful routing mechanism with which it is possible to define fine-grained entrypoints in Kong Gateway leading to different upstream services of your infrastructure. +

+ Depending on the protocol, one of the following attributes must be set: +
+ * `http`: At least one of `methods`, `hosts`, `headers`, or `paths` + * `https`: At least one of `methods`, `hosts`, `headers`, `paths`, or `snis` + * `tcp`: At least one of `sources` or `destinations` + * `tls`: at least one of `sources`, `destinations`, or `snis` + * `tls_passthrough`: set `snis` + * `grpc`: At least one of `hosts`, `headers`, or `paths` + * `grpcs`: At least one of `hosts`, `headers`, `paths`, or `snis` + * `ws`: At least one of `hosts`, `headers`, or `paths` + * `wss`: At least one of `hosts`, `headers`, `paths`, or `snis` +
+ + A route can't have both `tls` and `tls_passthrough` protocols at same time. +

+ + Learn more about the router: + * [Configure routes using expressions](https://docs.konghq.com/gateway/latest/key-concepts/routes/expressions/) + * [Router Expressions language reference](https://docs.konghq.com/gateway/latest/reference/expressions-language/) + name: Routes + - description: | + A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. Plugins let you add functionality to services that run behind a Kong Gateway instance, like authentication or rate limiting. + You can find more information about available plugins and which values each plugin accepts at the [Plugin Hub](https://docs.konghq.com/hub/). +

+ When adding a plugin configuration to a service, the plugin will run on every request made by a client to that service. If a plugin needs to be tuned to different values for some specific consumers, you can do so by creating a separate plugin instance that specifies both the service and the consumer, through the service and consumer fields. +

+ Plugins can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). +

+ **Bracket syntax for keys with periods:** + When submitting form data, keys that contain dots (e.g., `service.name`) should be enclosed in square brackets to avoid ambiguity: + + - Example: `config.resource_attributes[service.name]=kong-dev` + + - If necessary, URL encode the square brackets: `%5Bservice.name%5D`. + name: Plugins + - description: | + The consumer object represents a consumer - or a user - of a service. + You can either rely on Kong Gateway as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong Gateway and your existing primary datastore. + name: Consumers + - description: | + A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong Gateway to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. +

+ Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. +

+ If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string. + name: Certificates + - description: | + An SNI object represents a many-to-one mapping of hostnames to a certificate. +

+ A certificate object can have many hostnames associated with it. When Kong Gateway receives an SSL request, it uses the SNI field in the Client Hello to look up the certificate object based on the SNI associated with the certificate. + name: SNIs + - description: | + A target is an IP address or hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. +

+ To disable a target, post a new one with `weight=0`, or use the `DELETE` method to accomplish the same. + name: Targets + - description: | + A CA certificate object represents a trusted certificate authority. + These objects are used by Kong Gateway to verify the validity of a client or server certificate. + name: CA Certificates + - description: | + The upstream object represents a virtual hostname and can be used to load balance incoming requests over multiple services (targets). +

+ An upstream also includes a [health checker](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/), which can enable and disable targets based on their ability or inability to serve requests. + The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + name: Upstreams + - description: | + Vault objects are used to configure different vault connectors for [managing secrets](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/). + Configuring a vault lets you reference secrets from other entities. + This allows for a proper separation of secrets and configuration and prevents secret sprawl. +

+ For example, you could store a certificate and a key in a vault, then reference them from a certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure. +

+ Secrets rotation can be managed using [TTLs](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + name: Vaults + - description: | + A key object holds a representation of asymmetric keys in various formats. When Kong Gateway or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + name: Keys + - description: | + Keyring is the mechanism for storing sensitive data fields, such as consumer secrets, in an encrypted format within the database. This provides for encryption-at-rest security controls in a Kong Gateway cluster. + name: Keyring + - description: | + A JSON Web key set. Key sets are the preferred way to expose keys to plugins because they tell the plugin where to look for keys or have a scoping mechanism to restrict plugins to specific keys. + name: Key-sets + - description: | + The workspace object describes the workspace entity, which has an ID and a name. +

+ Workspaces provide a way to segment Kong Gateway entities. Entities in a workspace are isolated from those in other workspaces. + name: Workspaces + - description: | + A license entity lets you configure a license in your Kong Gateway cluster, in both traditional and hybrid mode deployments. + In hybrid mode deployments, the control plane sends licenses configured through the `/licenses` endpoint to all data planes in the cluster. + The data planes use the most recent `updated_at` license. + name: licenses + - description: | + Consumer groups enable the organization and categorization of consumers (users or applications) within an API ecosystem. + By grouping consumers together, you eliminate the need to manage them individually, providing a scalable, efficient approach to managing configurations. + name: consumer_groups + - description: | + Information routes + name: Information + - description: | + Admin routes + name: admins + - description: | + Group routes + name: groups + - description: | + Debug Routes + name: debug + - description: | + Kong Gateway's RBAC feature is configurable through Kong's Admin API or using Kong Manager. +

+ There are four basic entities involving RBAC: +

+ * User: The entity interacting with the system. Can be associated with zero, one, or more roles. For example: The user `bob` has the token `1234`. + * Role: Set of permissions (`role_endpoint` and `role_entity`). Has a name and can be associated with zero, one, or more permissions. For example: The user `bob` is associated with the role `developer`. + * `role_source`: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + * `role_endpoint`: A set of enabled or disabled actions. For example: The role `developer` has one `role_endpoint` and reads and writes to `/routes`. + * `role_entity`: A set of enabled or disabled actions. For example: The role `developer` has one `role_entity` attached to a UUID. + For the admin role in the default workspace, CRUD actions on /groups and /groups/* endpoints are disallowed. + For the workspace-admin role in non-default workspaces, CRUD actions on /groups and /groups/* endpoints are disallowed. + name: RBAC + - description: | + A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + name: filter-chains + - description: | + You can access request and database audit logs through the Admin API. The default order of audit log is by request timestamp - latest to oldest. +

+ For usage examples, see [Audit Logging in Kong Gateway](https://docs.konghq.com/gateway/latest/admin-api/audit-logs/). + name: audit-logs + - description: | + Event hooks are outbound calls from Kong Gateway. With event hooks, the Kong Gateway can communicate with target services or resources, letting the target know that an event was triggered. When an event is triggered in Kong, it calls a URL with information about that event. Event hooks add a layer of configuration for subscribing to worker events using the admin interface. Worker events are integrated into Kong Gateway to communicate within the gateway context. For example, when an entity is created, the Kong Gateway fires an event with information about the entity. Parts of the Kong Gateway codebase can subscribe to these events, then process the events using callbacks. +

+ Depending on the protocol, one of the following attributes must be set: +
+ * `webhook`: Makes a JSON POST request to a provided URL with the event data as a payload. Useful for building a middle tier integration (your own webhook that receives Kong hooks). Specific headers can be configured for the request. + * `webhook-custom`: Fully configurable request. Useful for building a direct integration with a service (for example, a Slack webhook). Because it’s fully configurable, it’s more complex to configure. It supports templating on a configurable body, a configurable form payload, and headers. + * `log`: This handler, which requires no configuration, logs the event and the content of the payload into the Kong Gateway logs. If using hybrid mode, the crud and dao:crud sources will log on the control plane logs and the balancer and rate-limiting-advanced sources will log on the data plane logs. + * `lambda`: This handler runs specified Lua code after an event is triggered. +

+ Event hooks do not work with Konnect yet. +

+ name: Event-hooks + - description: | + Retrieve information about the status of data planes when Kong Gateway is running in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache diff --git a/api-specs/Gateway-EE/3.9/kong-ee.yaml b/api-specs/Gateway-EE/3.9/kong-ee.yaml new file mode 100644 index 000000000000..cb3bf230d528 --- /dev/null +++ b/api-specs/Gateway-EE/3.9/kong-ee.yaml @@ -0,0 +1,16346 @@ +components: + parameters: + pagination-offset: + description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources + in: query + name: offset + schema: + type: string + pagination-size: + description: Number of resources to be returned. + in: query + name: size + schema: + default: 100 + maximum: 1000 + minimum: 1 + type: integer + pagination-tags-filter: + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using `,` to mean AND or using `/` to mean OR. + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + certificate_name_or_id: + name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + sni_name_or_id: + name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + tag: + name: tags + in: path + required: true + schema: + type: string + example: example + description: Tags are strings associated to entities in Kong. + log_level: + name: log_level + in: path + required: true + schema: + type: string + enum: + - info + - notice + - warn + - error + - crit + example: warn + description: Log levels are set in Kong's configuration. Log levels increase in order of their severity + target_id_or_target: + name: target_id_or_target + in: path + required: true + schema: + type: string + example: 'example.com:8000' + description: The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. + vault_id_or_prefix: + name: vault_id_or_prefix + in: path + required: true + schema: + type: string + example: env + description: The unique identifier or the prefix of the Vault to retrieve. + plugin_id: + name: plugin_id + in: path + required: true + schema: + type: string + example: response-ratelimiting + description: The unique identifier of the plugin to create or update. + upstream_id_or_name: + name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + key-set_id_or_name: + name: key-set_id_or_name + in: path + required: true + schema: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + description: The unique identifier or the `name` attribute of the Key Set that should be associated to the newly-created Key. + route_id_or_name: + name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + key_id_or_name: + name: key_id_or_name + in: path + required: true + schema: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725 + description: The unique identifier or the name of the Key to retrieve. + ca_certificate_id: + name: ca_certificate_id + description: ID of the related certificate + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + certificate_id: + name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + description: The unique identifier of the Certificate to retrieve. + service_id_or_name: + name: service_id_or_name + description: ID **or** name of the service to lookup + example: test-service + in: path + required: true + schema: + type: string + group_name_or_id: + name: group_name_or_id + in: path + required: true + schema: + anyOf: + - type: string + example: my_group + - type: string + example: 84a73fb8-50fc-44a7-a4d5-aa17728ee83f + type: string + example: my_group + description: The name or UUID of the consumer group. + group_name: + name: group_name + in: path + required: true + schema: + type: string + example: My-Group + description: A unique name for the consumer group you want to create. + consumer_name_or_id: + name: consumer_name_or_id + in: path + required: true + schema: + type: string + description: The name or UUID of the consumer to remove. + consumer_group_name_or_id: + name: consumer_group_name_or_id + in: path + required: true + schema: + type: string + description: The name or UUID of the consumer group to remove. + consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + license-id: + name: license-id + in: path + required: true + schema: + type: string + example: 30b4edb7-0847-4f65-af90-efbed8b0161f + description: The license's unique ID. + workspace_id_or_name: + name: workspace_id_or_name + in: path + required: true + schema: + type: string + example: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + description: ID or name of the workspace to look up. + workspace: + name: workspace + in: path + required: true + schema: + type: string + example: team-a + description: Name or ID of workspace + Gatewayapi_Consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + Gatewayapi_Pagination-tags-filter: + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using `,` to mean AND or using `/` to mean OR. + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + filter_chain_id: + name: filter_chain_id + in: path + required: true + schema: + type: string + description: The unique identifier of the filter chain to retrieve. + beforeAuditLogFilter: + name: before_audit_log_filter + in: query + required: false + schema: + $ref: '#/components/schemas/RequestTimestampFilterSchema' + description: | + Before filter could be used to request audit log data that was recorded before certain time (exclusive). + It can either be a timestamp as Unix Epoch or a string following RFC3339 Schema (without fractions of a second) - ex: '2024-04-25T15:03:24Z' + afterAuditLogFilter: + name: after_audit_log_filter + in: query + required: false + schema: + $ref: '#/components/schemas/RequestTimestampFilterSchema' + description: | + After filter could be used to request audit log data that was recorded after certain time (inclusive). + It can either be a timestamp as Unix Epoch or a string following RFC3339 Schema (without fractions of a second) - ex: '2024-04-25T15:03:24Z' + schemas: + UnauthorizedError: + type: object + properties: + status: + type: integer + message: + type: string + required: + - status + - message + CA-Certificate: + description: A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f260 + type: object + properties: + cert: + description: PEM-encoded public certificate of the CA. + type: string + cert_digest: + description: SHA256 hex digest of the public certificate. This field is read-only and it cannot be set by the caller, the value is automatically computed. + type: string + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: tag + Certificate: + description: A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string according to the following order, main certificate on the top, followed by any intermediates. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + properties: + cert: + description: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + cert_alt: + description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + key: + description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + key_alt: + description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + snis: + description: > + A list of SNIs associated with the certificate. + type: array + items: + type: string + format: hostname + type: object + Consumer: + 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. + example: + custom_id: '4200' + id: 8a388226-20e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + 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 + id: + type: string + tags: + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + username: + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + type: string + type: object + x-examples: + Consumer Object: + custom_id: '4200' + id: 8a388226-80e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + Key: + description: A Key object holds a representation of asymmetric keys in various formats. When Kong or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + example: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + jwk: + description: A JSON Web Key represented as a string. + type: string + kid: + description: A unique identifier for a key. + type: string + name: + description: The name to associate with the given keys. + type: string + pem: + description: A keypair in PEM format. + properties: + private_key: + type: string + public_key: + type: string + type: object + set: + additionalProperties: false + description: The id (an UUID) of the key-set with which to associate the key. + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Key-set: + example: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + tags: + - idp-keys + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + name: + type: string + tags: + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Key-set + Plugin: + description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). When adding a Plugin Configuration to a Service, every request made by a client to that Service will run said Plugin. If a Plugin needs to be tuned to different values for some specific Consumers, you can do so by creating a separate plugin instance that specifies both the Service and the Consumer, through the `service` and `consumer` fields. + example: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + properties: + config: + description: The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/). + type: object + consumer: + additionalProperties: false + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer. + properties: + id: + type: string + type: object + consumer_group: + additionalProperties: false + description: If set, the plugin will activate only for requests where the specified consumer group has been authenticated. (Note that some plugins can not be restricted to consumers groups this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer Groups + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the plugin is applied. + type: boolean + id: + type: string + name: + description: "The name of the plugin that's going to be added. The plugin must be installed in every Kong instance separately." + type: string + ordering: + type: object + protocols: + default: + - grpc + - grpcs + - http + - https + description: A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `tcp` and `tls`. + items: + type: string + type: array + route: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the Route being used. + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched. + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the plugin for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Route: + description: Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service. The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the Route. + example: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + destinations: + description: A list of IP destinations of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + properties: + default: {} + type: object + type: array + headers: + description: One or more lists of values indexed by header name that will cause this Route to match if present in the request. The `Host` header cannot be used with this `attribute:` hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression. + type: object + hosts: + description: A list of domain names that match this Route. Note that the hosts value is case sensitive. + items: + type: string + type: array + https_redirect_status_code: + default: 426 + description: The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. This config applies only if the Route is configured to only accept the `https` protocol. + type: integer + id: + type: string + methods: + description: A list of HTTP methods that match this Route. + items: + type: string + type: array + name: + description: The name of the Route. Route names must be unique, and they are case sensitive. For example, there can be two different Routes named "test" and "Test". + type: string + path_handling: + default: v0 + description: Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. + type: string + paths: + description: A list of paths that match this Route. + items: + type: string + type: array + preserve_host: + default: false + description: "When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the service's `host`." + type: boolean + protocols: + default: + - http + - https + description: An array of the protocols this Route should allow. See the [Route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error. + items: + type: string + type: array + regex_priority: + default: 0 + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + type: integer + request_buffering: + default: true + description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. + type: boolean + response_buffering: + default: true + description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. + type: boolean + service: + additionalProperties: false + description: The Service this route is associated to. This is where the route proxies traffic to. + properties: + id: + type: string + type: object + expression: + description: The route expression used for advanced routing scenarios. This field is used to evaluate route matches based on complex criteria beyond the standard routing fields. + type: string + priority: + description: A number used to specify the matching order for expression routes. The higher the `priority`, the sooner a route will be evaluated. This field is ignored unless `expression` field is set. The value must be between 0 and 2^46 - 1. + type: integer + default: 0 + snis: + description: A list of SNIs that match this route when using stream routing. + items: + type: string + type: array + sources: + description: A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + properties: + default: {} + type: object + type: array + strip_path: + default: true + description: When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL. + type: boolean + tags: + description: An optional set of strings associated with the route for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + SNI: + description: An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate. + example: + certificate: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + id: 36c4566c-14cc-4132-9011-4139fcbbe50a + name: some.example.org + properties: + certificate: + additionalProperties: false + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + name: + description: The SNI name to associate with the given certificate. + type: string + tags: + description: An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Service: + description: Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc. The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its `protocol`, `host`, `port` and `path` individually. Services are associated to routes (a Service can have many routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a route is matched, Kong proxies the request to its associated Service. See the [Proxy Reference][proxy-reference] for a detailed explanation of how Kong proxies traffic. + example: + host: example.internal + id: 49fd316e-c457-481c-9fc7-8079153e4f3c + name: example-service + path: / + port: 80 + protocol: http + properties: + ca_certificates: + description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream servers TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). + items: + type: string + type: array + client_certificate: + additionalProperties: false + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + type: object + connect_timeout: + default: 60000 + description: The timeout in milliseconds for establishing a connection to the upstream server. + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the Service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). + type: boolean + host: + description: The host of the upstream server. Note that the host value is case sensitive. + type: string + id: + type: string + name: + description: The Service name. + type: string + path: + description: The path to be used in requests to the upstream server. + type: string + port: + default: 80 + description: The upstream server port. + type: integer + protocol: + default: http + description: The protocol used to communicate with the upstream. + type: string + read_timeout: + default: 60000 + description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. + type: integer + retries: + default: 5 + description: The number of retries to execute upon failure to proxy. + type: integer + tags: + description: An optional set of strings associated with the Service for grouping and filtering. + items: + type: string + type: array + tls_verify: + description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected. + type: boolean + tls_verify_depth: + description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected. + type: integer + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + url: + description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses. + type: string + write_timeout: + default: 60000 + description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. + type: integer + type: object + title: Service + Target: + description: A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. To disable a target, post a new one with `weight=0`; alternatively, use the `DELETE` convenience method to accomplish the same. The current target object definition is the one with the latest `created_at`. + example: + id: 089292a7-ba3d-4d88-acf0-97b4b2e2621a + target: 203.0.113.42 + upstream: + id: 5f1d7e76-2fed-4806-a6af-869984f025cb + weight: 100 + properties: + created_at: + description: Unix epoch when the resource was created. + type: number + id: + type: string + tags: + description: An optional set of strings associated with the Target for grouping and filtering. + items: + type: string + type: array + target: + description: The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record. + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: number + upstream: + additionalProperties: false + properties: + id: + type: string + type: object + weight: + default: 100 + description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + type: object + Upstream: + description: The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + example: + algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + properties: + algorithm: + default: round-robin + description: Which load balancing algorithm to use. + type: string + client_certificate: + additionalProperties: false + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + hash_fallback: + default: none + description: What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`. + type: string + hash_fallback_header: + description: The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. + type: string + hash_fallback_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + type: string + hash_fallback_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + type: string + hash_on: + default: none + description: What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. + type: string + hash_on_cookie: + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + type: string + hash_on_cookie_path: + default: / + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + type: string + hash_on_header: + description: The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. + type: string + hash_on_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + type: string + hash_on_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + type: string + healthchecks: + properties: + active: + properties: + concurrency: + default: 10 + type: integer + headers: + type: object + healthy: + properties: + http_statuses: + default: + - 200 + - 302 + items: + type: integer + type: array + interval: + default: 0 + type: number + successes: + default: 0 + type: integer + type: object + http_path: + default: / + type: string + https_sni: + type: string + https_verify_certificate: + default: true + type: boolean + timeout: + default: 1 + type: number + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + items: + type: integer + type: array + interval: + default: 0 + type: number + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + passive: + properties: + healthy: + properties: + http_statuses: + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + items: + type: integer + type: array + successes: + default: 0 + type: integer + type: object + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 500 + - 503 + items: + type: integer + type: array + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + threshold: + default: 0 + type: number + type: object + host_header: + description: The hostname to be used as `Host` header when proxying requests through Kong. + type: string + id: + type: string + name: + description: This is a hostname, which must be equal to the `host` of a Service. + type: string + slots: + default: 10000 + description: The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`. + type: integer + tags: + description: An optional set of strings associated with the Upstream for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + use_srv_name: + default: false + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`. + type: boolean + type: object + Vault: + description: Vault entities are used to configure different Vault connectors. Examples of Vaults are Environment Variables, HashiCorp Vault and AWS Secrets Manager. Configuring a Vault allows referencing the secrets with other entities. For example a certificate entity can store a reference to a certificate and key, stored in a vault, instead of storing the certificate and key within the entity. This allows a proper separation of secrets and configuration and prevents secret sprawl. + example: + config: + prefix: vaults.config.resurrect_ttl + description: environment variable based vault + id: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + name: env + tags: + - foo + - bar + properties: + config: + description: The configuration properties for the Vault which can be found on the [vaults documentation page](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + type: object + properties: + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + enum: + - vaults.config.resurrect_ttl + - vaults.config.neg_ttl + - vaults.config.ttl + required: + - prefix + created_at: + description: Unix epoch when the resource was created. + type: integer + description: + description: The description of the Vault entity. + type: string + id: + type: string + name: + description: The name of the vault that's going to be added. The vault implementation must be installed in every Kong instance. + type: string + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + tags: + description: An optional set of strings associated with the Vault for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + Workspace: + type: object + properties: + comment: + type: string + config: + type: object + properties: + meta: + type: object + portal: + default: false + type: boolean + description: Portal enabled + portal_access_request_email: + type: boolean + portal_application_request_email: + type: boolean + portal_application_status_email: + type: boolean + portal_approved_email: + type: boolean + portal_auth: + type: string + portal_auth_conf: + type: string + portal_auto_approve: + type: boolean + portal_cors_origins: + type: array + items: + type: string + portal_developer_meta_fields: + default: '[{"label":"Full Name","title":"full_name","validator":{"required":true,"type":"string"}}]' + type: string + portal_emails_from: + type: string + portal_emails_reply_to: + type: string + portal_invite_email: + type: boolean + portal_is_legacy: + type: boolean + portal_reset_email: + type: boolean + portal_reset_success_email: + type: boolean + portal_session_conf: + type: string + portal_smtp_admin_emails: + type: array + items: + type: string + portal_token_exp: + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + description: The unique UUID for this resource. + meta: + type: object + properties: + color: + type: string + thumbnail: + type: string + name: + type: string + x-examples: + Example 1: + comment: string + config: + meta: {} + portal: false + portal_access_request_email: true + portal_application_request_email: true + portal_application_status_email: true + portal_approved_email: true + portal_auth: string + portal_auth_conf: string + portal_auto_approve: true + portal_cors_origins: + - string + portal_developer_meta_fields: >- + [{"label":"Full Name","title":"full_name","validator":{"required":true,"type":"string"}}] + portal_emails_from: string + portal_emails_reply_to: string + portal_invite_email: true + portal_is_legacy: true + portal_reset_email: true + portal_reset_success_email: true + portal_session_conf: string + portal_smtp_admin_emails: + - string + portal_token_exp: 0 + created_at: 0 + id: string + meta: + color: string + thumbnail: string + name: string + description: Workspaces provide a way to segment Kong entities. + pagination-offset-response: + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + type: string + Filter-chains: + type: object + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: my-chain + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + - name: go-rate-limiting + enabled: true + config: '{ "minute": 30 }' + - name: rust-response-transformer + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: + - my-tag + description: A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + title: Filter-chains + properties: + id: + type: string + description: The unique identifier or the name attribute of the route that should be associated to the newly created filter chain. + example: ce44eef5-41ed-47f6-baab-f725cecf98c7 + format: uuid + name: + type: string + description: | + The name of the filter chain. + example: my-chain + created_at: + type: integer + example: 1422386534 + updated_at: + type: integer + example: 1422386534 + enabled: + type: boolean + description: | + Whether the filter chain is applied. Default: true. + default: true + route: + description: The route to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `route.id=` or `route.name=`. In JSON format, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: The service to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `service.id=` or `service.name=`. In JSON format, use `"service":{"id":""}` or `"service":{"name":""}`. + example: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + type: array + description: An array of filter definitions. Each filter is an object containing a mandatory name, an optional config, and a boolean enabled setting. + items: + type: object + properties: + name: + type: string + description: | + The name of the filter + example: go-rate-limiting + enabled: + type: boolean + description: Enable the filter + config: + type: string + description: configuration filter headers + example: '{ \"minute\": 30 }' + tags: + type: array + items: + type: string + RequestTimestampFilterSchema: + oneOf: + - type: string + pattern: '^(\d+|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)$' + - type: integer + responses: + HTTP401Error: + content: + application/json: + examples: + DuplicateApiKey: + summary: Duplicate API key found + value: + message: Duplicate API key found + status: 401 + InvalidAuthCred: + summary: Invalid authentication credentials + value: + message: Unauthorized + status: 401 + NoAPIKey: + summary: No API key found + value: + message: No API key found in request + status: 401 + schema: + $ref: '#/components/schemas/UnauthorizedError' + description: Unauthorized + tags-response: + description: Tags response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - entity_name: services + entity_id: acf60b10-125c-4c1a-bffe-6ed55daefba4 + tag: s1 + offset: c47139f3-d780-483d-8a97-17e9adc5a7ab + next: /tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab + properties: + data: + type: array + items: + type: object + properties: + entity_name: + type: string + example: services + description: The name of the entity that corresponds to a tag + entity_id: + type: string + example: c87440e1-0496-420b-b06f-dac59544bb6c + description: The unique ID for the entity that is attached to the tag + tag: + type: string + example: example + description: The tag + offset: + type: string + example: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + next: + type: string + example: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + examples: + Tags response: + value: + data: + - entity_name: services + entity_id: c87440e1-0496-420b-b06f-dac59544bb6c + tag: example + offset: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + next: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + key-set-response: + description: Key set object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - idp-keys + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + id: + type: string + example: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + created_at: + type: integer + description: Unix epoch when the resource was last created. + example: 1422386534 + updated_at: + type: integer + description: | + Unix epoch when the resource was last updated. + example: 1422386534 + tags: + type: array + description: | + The name to associate with the given key-set. + items: + type: string + next: + type: string + description: | + Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + example: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + examples: + example: + value: + id: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: my-key_set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - string + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + plugin-response: + description: A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. + content: + application/json: + schema: + type: object + properties: + id: + type: string + name: + type: string + description: The name of the plugin thats going to be added. Currently, the plugin must be installed in every Kong instance separately. + example: rate-limiting + created_at: + type: integer + description: Unix epoch when the resource was created. + route: + type: string + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default, `null`.With form-encoded, the notation is `route.id=` or `route.name=`. With JSON, use `route:{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique within a workspace for Kong Gateway Enterprise. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the plugin for grouping and filtering. + items: + type: string + ordering: + type: object + description: | + Describes a dependency to another plugin to determine plugin ordering during the access phase. + - `before`: The plugin will be executed before a specified plugin or list of plugins. + - `after`: The plugin will be executed after a specified plugin or list of plugins. + properties: + before: + type: array + items: + type: string + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + examples: + Plugin response: + value: + data: + - id: 02621eee-8309-4bf6-b36b-a82017a5393e + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + - id: 66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - tcp + - tls + enabled: true + tags: + - admin + - high-priority + - critical + ordering: + after: + - plugin-name + next: 'http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + sni-response: + description: SNI response object + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + name: my-sni + created_at: 1422386534 + tags: + - user-level + - low-priority + certificate: + id: a3ad71a8-6685-4b03-a101-980a953544f6 + - id: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: my-sni + created_at: 1422386534 + tags: + - admin + - high-priority + - critical + certificate: + id: 4e8d95d4-40f2-4818-adcb-30e00c349618 + next: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + description: Array of SNIs + items: + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + description: The unique identifier or the name attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + name: + type: string + description: | + The SNI name to associate with the given certificate. + example: my-sni + created_at: + type: integer + example: 1422386534 + description: | + Unix epoch when the resource was created. + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + certificate: + type: object + description: | + The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + properties: + id: + type: string + example: 2e013e8-7623-4494-a347-6d29108ff68b + description: The unique identifier or the name attribute of the Certificate whose SNIs + next: + type: string + example: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + consumer-response-data: + description: The consumer object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + - id: 01c23299-839c-49a5-a6d5-8864c09184af + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier or the name attribute of the consumer. + example: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1422386534 + username: + type: string + description: The unique username of the consumer. You must send either this field or` custom_i`d with the request. + example: my-username + custom_id: + type: string + 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. + example: my-custom-id + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + example: admin + next: + type: string + description: Pagination information + example: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + consumer_group_response: + description: The consumer group response body + content: + application/json: + schema: + type: object + properties: + data: + type: array + description: The data array contains consumer group objects + items: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1719859003 + id: + type: string + description: The UUID of the consumer group + example: 0d8f5353-8dd2-4013-859a-21510b970a64 + name: + type: string + description: The name of the consumer group + example: group2 + tags: + type: array + description: An optional set of strings associated with the consumer group for grouping and filtering. + items: + type: string + example: example_tag + updated_at: + type: integer + description: Unix epoch when the resource was last updated. + example: 1719859003 + next: + type: string + description: Link to the next page of results, if applicable + example: null + x-examples: + Example 1: + data: + - created_at: 1719859003 + id: 0d8f5353-8dd2-4013-859a-21510b970a64 + name: group2 + tags: [] + updated_at: 1719859003 + - created_at: 1719858982 + id: 7012a570-e372-4280-92db-7fbbe4af80bb + name: group1 + tags: [] + updated_at: 1719858982 + - created_at: 1719859346 + id: 9faf2f1b-2110-4690-8b64-c70dc14aa51a + name: group3 + tags: null + updated_at: 1719859346 + next: null + Consumer group example: + data: + - created_at: 1719859003 + id: 0d8f5353-8dd2-4013-859a-21510b970a64 + name: group2 + tags: [] + updated_at: 1719859003 + next: null + add_consumer_to_group_response: + description: The object returns information about the consumer and the group + content: + application/json: + schema: + type: object + x-examples: + Example 1: + consumer: + created_at: 1638918560 + custom_id: null + id: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + tags: null + type: 0 + username: BarryAllen + username_lower: barryallen + consumer_groups: + - created_at: 1638918476 + id: e2c3f16e-22c7-4ef4-b6e4-ab25c522b339 + name: JL + tags: null + properties: + consumer: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1638918560 + custom_id: + type: string + 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. + nullable: true + id: + type: string + description: The UUID for the consumer + tags: + type: object + description: An optional set of strings associated with consumer group for grouping and filtering. + nullable: true + type: + type: integer + default: 0 + example: 0 + username: + type: string + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + username_lower: + type: string + description: A lowercase representation of the username + consumer_groups: + type: array + items: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + id: + type: string + description: The UUID for the consumer group + name: + type: string + description: The name of the consumer group + tags: + type: object + description: An optional set of strings associated with consumer group for grouping and filtering. + nullable: true + examples: + Example: + value: + consumer: + created_at: 0 + custom_id: null + id: string + tags: null + type: 0 + username: string + username_lower: string + consumer_groups: + - created_at: 0 + id: string + name: string + tags: + red: null + consumer_response: + description: A consumer response object + content: + application/json: + schema: + type: object + properties: + data: + type: array + description: The data array contains consumer objects + items: + type: object + properties: + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1719859293 + custom_id: + type: string + description: Custom ID of the consumer + example: consumer_id3 + id: + type: string + example: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + description: The consumer ID + tags: + type: array + description: Tags associated with the consumer + items: + type: string + example: test + type: + type: integer + default: 0 + example: 0 + updated_at: + type: integer + description: Unix epoch when the resource was last updated. + example: 1719859293 + username: + type: string + example: consumer3 + description: The username of the consumer + username_lower: + type: string + example: consumer3 + description: Lowercase representation of the consumer username. + next: + type: string + description: Link to the next page of results, if applicable + example: null + x-examples: + Example 1: + data: + - created_at: 1719859293 + custom_id: consumer_id3 + id: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + tags: null + type: 0 + updated_at: 1719859293 + username: consumer3 + username_lower: consumer3 + - created_at: 1719858943 + custom_id: consumer_id + id: 73b74f15-5185-4b16-a2fc-3c2fd834ba6c + tags: null + type: 0 + updated_at: 1719858943 + username: consumer + username_lower: consumer + - created_at: 1719858965 + custom_id: consumer_id2 + id: f9383372-7bf4-4275-8bbc-4f89d7a38a23 + tags: null + type: 0 + updated_at: 1719858965 + username: consumer2 + username_lower: consumer2 + next: null + One consumer: + data: + - created_at: 1719859293 + custom_id: consumer_id3 + id: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + tags: null + type: 0 + updated_at: 1719859293 + username: consumer3 + username_lower: consumer3 + next: null + Multiple consumers: + data: + - created_at: 1719859293 + custom_id: consumer_id3 + id: 1cf590ba-4b23-46fa-9e8d-4296213e2ac6 + tags: null + type: 0 + updated_at: 1719859293 + username: consumer3 + username_lower: consumer3 + - created_at: 1719858943 + custom_id: consumer_id + id: 73b74f15-5185-4b16-a2fc-3c2fd834ba6c + tags: null + type: 0 + updated_at: 1719858943 + username: consumer + username_lower: consumer + - created_at: 1719858965 + custom_id: consumer_id2 + id: f9383372-7bf4-4275-8bbc-4f89d7a38a23 + tags: null + type: 0 + updated_at: 1719858965 + username: consumer2 + username_lower: consumer2 + next: null + license-response: + description: The license response object. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + created_at: 1500508800 + id: 30b4edb7-0847-4f65-af90-efbed8b0161f + payload: '{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-21","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb","version":"1"}}' + updated_at: 1500508800 + properties: + created_at: + type: integer + example: 1500508800 + id: + type: string + example: 30b4edb7-0847-4f65-af90-efbed8b0161f + description: The UUID of the license + payload: + type: string + example: '{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}' + description: | + The Kong Gateway license in JSON format. + updated_at: + type: integer + example: 1500508800 + examples: + Active license: + value: + created_at: 1500508800 + id: 30b4edb7-0847-4f65-af90-efbed8b0161f + payload: '{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}' + updated_at: 1500508800 + No license: + value: + data: [] + next: null + report-response: + description: Fields available in the report + content: + application/json: + schema: + type: object + x-examples: + Example 1: + counters: + - bucket: 2021-12 + request_count: 0 + db_version: postgres 9.6.19 + kong_version: 3.2.2.1 + license_key: ASDASDASDASDASDASDASDASDASD_ASDASDA + rbac_users: 0 + services_count: 0 + system_info: + cores: 4 + hostname: 13b867agsa008 + uname: Linux x86_64 + workspaces_count: 1 + properties: + counters: + type: array + description: | + Counts the number of requests made in a given month. + items: + type: object + properties: + bucket: + type: string + description: Year and month when the requests were processed. If the value in bucket is UNKNOWN, then the requests were processed before Kong Gateway 2.7.0.1. + example: 2021-12 + request_count: + type: integer + description: Number of requests processed in the given month and year. + example: 0 + db_version: + type: string + description: | + The type and version of the data store Kong Gateway is using. + example: postgres 9.6.19 + kong_version: + type: string + description: | + The version of the Kong Gateway instance. + example: 3.2.2.1 + license_key: + type: string + description: | + An encrypted identifier for the current license key. If no license is present, the field displays as UNLICENSED. + example: ASDASDASDASDASDASDASDASDASD_ASDASDA + rbac_users: + type: integer + description: | + The number of users registered with through RBAC. + example: 0 + services_count: + type: integer + description: | + The number of configured services in the Kong Gateway instance. + example: 0 + system_info: + type: object + description: | + Displays information about the system running Kong Gateway. + properties: + cores: + type: integer + description: Number of CPU cores on the node + example: 11 + hostname: + type: string + description: Encrypted system hostname + example: 13b867agsa008 + uname: + type: string + description: Operating system + example: Linux x86_64 + workspaces_count: + type: integer + description: | + The number of workspaces configured in the Kong Gateway instance. + example: 1 + key-ring-response: + description: The contents of the keyring. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + ids: + - LaW1urRQ + active: LaW1urRQ + description: The keyring object contains an array of keyring ids. + properties: + ids: + type: array + description: The list of the active key IDs + items: + type: string + example: LaW1urRQ + active: + type: string + example: LaW1urRQ + description: The ID of the active key. + examples: + example: + value: + ids: + - LaW1urRQ + active: LaW1urRQ + keyring-generate-response: + description: Keyring response object + content: + application/json: + schema: + type: object + properties: + key: + type: string + id: + type: string + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + workspace-response: + description: The workspace response object. + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + workspace_create_response: + description: The response object for creating a new workspace. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + total: 1 + data: + - created_at: 1529627841000 + id: a43fc3f9-98e4-43b0-b703-c3b1004980d5 + name: default + properties: + total: + type: integer + description: The amount of workspaces. + data: + type: array + description: The array of workspaces + items: + type: object + properties: + created_at: + type: integer + example: 1529627841000 + description: The time and date of workspace creation. + id: + type: string + example: a43fc3f9-98e4-43b0-b703-c3b1004980d5 + description: The unique ID of the workspace + name: + type: string + description: The name assigned in the request body. + example: default + get-endpoints: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: string + x-examples: + Example 1: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /admins + - /admins/password_resets + - /admins/register + - /admins/self/password + - /admins/self/token + - '/admins/{admins}' + - '/admins/{admins}/consumer' + - '/admins/{admins}/rbac_user' + - '/admins/{admin}/roles' + - '/admins/{admin}/workspaces' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumer_groups + - '/consumer_groups/{consumer_groups}' + - '/consumer_groups/{consumer_groups}/consumers' + - '/consumer_groups/{consumer_groups}/consumers/{consumers}' + - '/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - '/consumer_groups/{consumer_groups}/plugins' + - '/consumer_groups/{consumer_groups}/plugins/{plugins}' + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/consumer_groups' + - '/consumers/{consumers}/consumer_groups/{consumer_groups}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /developers + - /developers/export + - /developers/invite + - /developers/roles + - '/developers/roles/{rbac_roles}' + - '/developers/{developers}' + - '/developers/{developers}/applications' + - '/developers/{developers}/applications/{applications}' + - '/developers/{developers}/applications/{applications}/application_instances' + - '/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/consumer' + - '/developers/{developers}/credentials/{plugin}' + - '/developers/{developers}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/rbac_user' + - '/developers/{email_or_id}/plugins/' + - '/developers/{email_or_id}/plugins/{id}' + - /document_objects + - '/document_objects/{document_objects}' + - '/document_objects/{document_objects}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keyring + - /keyring/activate + - /keyring/active + - /keyring/export + - /keyring/generate + - /keyring/import + - /keyring/import/raw + - /keyring/recover + - /keyring/remove + - /keyring/vault/sync + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/consumer_group' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /rbac/roles + - '/rbac/roles/{rbac_roles}' + - '/rbac/roles/{rbac_roles}/endpoints' + - '/rbac/roles/{rbac_roles}/endpoints/permissions' + - '/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - '/rbac/roles/{rbac_roles}/entities' + - '/rbac/roles/{rbac_roles}/entities/permissions' + - '/rbac/roles/{rbac_roles}/entities/{entity_id}' + - '/rbac/roles/{rbac_roles}/permissions' + - /rbac/users + - '/rbac/users/{rbac_users}' + - '/rbac/users/{rbac_users}/admins' + - '/rbac/users/{rbac_users}/admins/{admins}' + - '/rbac/users/{rbac_users}/developers' + - '/rbac/users/{rbac_users}/developers/{developers}' + - '/rbac/users/{rbac_users}/permissions' + - '/rbac/users/{rbac_users}/roles' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/document_objects' + - '/services/{services}/document_objects/{document_objects}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + - /workspaces + - '/workspaces/{workspaces}' + - '/workspaces/{workspaces}/meta' + - '/{workspace_name}/kong' + - workspace_/acls + - 'workspace_/acls/{acls}' + - 'workspace_/acls/{acls}/consumer' + - workspace_/acme + - workspace_/acme/certificates + - 'workspace_/acme/certificates/{certificates}' + - workspace_/acme_storage + - 'workspace_/acme_storage/{acme_storage}' + - workspace_/admins + - workspace_/admins/password_resets + - workspace_/admins/register + - workspace_/admins/self/password + - workspace_/admins/self/token + - 'workspace_/admins/{admins}' + - 'workspace_/admins/{admins}/consumer' + - 'workspace_/admins/{admins}/rbac_user' + - 'workspace_/admins/{admin}/roles' + - 'workspace_/admins/{admin}/workspaces' + - workspace_/applications + - 'workspace_/applications/{applications}' + - 'workspace_/applications/{applications}/application_instances' + - 'workspace_/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/applications/{applications}/consumer' + - 'workspace_/applications/{applications}/credentials/{plugin}' + - 'workspace_/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/applications/{applications}/developer' + - workspace_/auth + - workspace_/basic-auths + - 'workspace_/basic-auths/{basicauth_credentials}' + - 'workspace_/basic-auths/{basicauth_credentials}/consumer' + - workspace_/ca_certificates + - 'workspace_/ca_certificates/{ca_certificates}' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - workspace_/cache + - 'workspace_/cache/{key}' + - workspace_/certificates + - 'workspace_/certificates/{certificates}' + - 'workspace_/certificates/{certificates}/services' + - 'workspace_/certificates/{certificates}/services/{services}' + - 'workspace_/certificates/{certificates}/snis' + - 'workspace_/certificates/{certificates}/snis/{snis}' + - 'workspace_/certificates/{certificates}/upstreams' + - 'workspace_/certificates/{certificates}/upstreams/{upstreams}' + - workspace_/clustering/data-planes + - workspace_/clustering/status + - workspace_/config + - workspace_/consumer_groups + - 'workspace_/consumer_groups/{consumer_groups}' + - 'workspace_/consumer_groups/{consumer_groups}/consumers' + - 'workspace_/consumer_groups/{consumer_groups}/consumers/{consumers}' + - 'workspace_/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - 'workspace_/consumer_groups/{consumer_groups}/plugins' + - 'workspace_/consumer_groups/{consumer_groups}/plugins/{plugins}' + - workspace_/consumers + - 'workspace_/consumers/{consumers}' + - 'workspace_/consumers/{consumers}/acls' + - 'workspace_/consumers/{consumers}/acls/{acls}' + - 'workspace_/consumers/{consumers}/admins' + - 'workspace_/consumers/{consumers}/admins/{admins}' + - 'workspace_/consumers/{consumers}/applications' + - 'workspace_/consumers/{consumers}/applications/{applications}' + - 'workspace_/consumers/{consumers}/basic-auth' + - 'workspace_/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - 'workspace_/consumers/{consumers}/consumer_groups' + - 'workspace_/consumers/{consumers}/consumer_groups/{consumer_groups}' + - 'workspace_/consumers/{consumers}/developers' + - 'workspace_/consumers/{consumers}/developers/{developers}' + - 'workspace_/consumers/{consumers}/hmac-auth' + - 'workspace_/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - 'workspace_/consumers/{consumers}/jwt' + - 'workspace_/consumers/{consumers}/jwt/{jwt_secrets}' + - 'workspace_/consumers/{consumers}/key-auth' + - 'workspace_/consumers/{consumers}/key-auth/{keyauth_credentials}' + - 'workspace_/consumers/{consumers}/key-auth-enc' + - 'workspace_/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - 'workspace_/consumers/{consumers}/login_attempts' + - 'workspace_/consumers/{consumers}/login_attempts/{login_attempts}' + - 'workspace_/consumers/{consumers}/mtls-auth' + - 'workspace_/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/oauth2' + - 'workspace_/consumers/{consumers}/oauth2/{oauth2_credentials}' + - 'workspace_/consumers/{consumers}/plugins' + - 'workspace_/consumers/{consumers}/plugins/{plugins}' + - 'workspace_/debug/cluster/log-level/{log_level}' + - workspace_/debug/node/log-level + - 'workspace_/debug/node/log-level/{log_level}' + - workspace_/debug/profiling/cpu + - workspace_/debug/profiling/gc-snapshot + - workspace_/debug/profiling/memory + - workspace_/degraphql_routes + - 'workspace_/degraphql_routes/{degraphql_routes}' + - 'workspace_/degraphql_routes/{degraphql_routes}/service' + - workspace_/developers + - workspace_/developers/export + - workspace_/developers/invite + - workspace_/developers/roles + - 'workspace_/developers/roles/{rbac_roles}' + - 'workspace_/developers/{developers}' + - 'workspace_/developers/{developers}/applications' + - 'workspace_/developers/{developers}/applications/{applications}' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/consumer' + - 'workspace_/developers/{developers}/credentials/{plugin}' + - 'workspace_/developers/{developers}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/rbac_user' + - 'workspace_/developers/{email_or_id}/plugins/' + - 'workspace_/developers/{email_or_id}/plugins/{id}' + - workspace_/document_objects + - 'workspace_/document_objects/{document_objects}' + - 'workspace_/document_objects/{document_objects}/service' + - workspace_/endpoints + - workspace_/entities/migrate + - workspace_/event-hooks + - workspace_/event-hooks/sources + - 'workspace_/event-hooks/sources/{source}' + - 'workspace_/event-hooks/sources/{source}/{event}' + - 'workspace_/event-hooks/{event_hooks}' + - 'workspace_/event-hooks/{event_hooks}/ping' + - 'workspace_/event-hooks/{event_hooks}/test' + - workspace_/files + - workspace_/files/* + - workspace_/files/partials/* + - 'workspace_/files/{files}' + - workspace_/filter-chains + - 'workspace_/filter-chains/{filter_chains}' + - 'workspace_/filter-chains/{filter_chains}/route' + - 'workspace_/filter-chains/{filter_chains}/service' + - workspace_/graphql-proxy-cache-advanced + - 'workspace_/graphql-proxy-cache-advanced/{cache_key}' + - 'workspace_/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/graphql-rate-limiting-advanced/costs + - 'workspace_/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - workspace_/graphql_ratelimiting_advanced_cost_decoration + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - workspace_/groups + - 'workspace_/groups/{groups}' + - 'workspace_/groups/{groups}/roles' + - workspace_/hmac-auths + - 'workspace_/hmac-auths/{hmacauth_credentials}' + - 'workspace_/hmac-auths/{hmacauth_credentials}/consumer' + - workspace_/jwt-signer/jwks + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}' + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - workspace_/jwts + - 'workspace_/jwts/{jwt_secrets}' + - 'workspace_/jwts/{jwt_secrets}/consumer' + - workspace_/key-auths + - 'workspace_/key-auths/{keyauth_credentials}' + - 'workspace_/key-auths/{keyauth_credentials}/consumer' + - workspace_/key-auths-enc + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}' + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}/consumer' + - workspace_/key-sets + - 'workspace_/key-sets/{key_sets}' + - 'workspace_/key-sets/{key_sets}/keys' + - 'workspace_/key-sets/{key_sets}/keys/{keys}' + - workspace_/keyring + - workspace_/keyring/activate + - workspace_/keyring/active + - workspace_/keyring/export + - workspace_/keyring/generate + - workspace_/keyring/import + - workspace_/keyring/import/raw + - workspace_/keyring/recover + - workspace_/keyring/remove + - workspace_/keyring/vault/sync + - workspace_/keys + - 'workspace_/keys/{keys}' + - 'workspace_/keys/{keys}/set' + - workspace_/konnect_applications + - 'workspace_/konnect_applications/{konnect_applications}' + - workspace_/license/report + - workspace_/licenses + - 'workspace_/licenses/{licenses}' + - workspace_/login_attempts + - 'workspace_/login_attempts/{login_attempts}' + - 'workspace_/login_attempts/{login_attempts}/consumer' + - workspace_/metrics + - workspace_/mtls-auths + - 'workspace_/mtls-auths/{mtls_auth_credentials}/consumer' + - workspace_/mtls_auth_credentials + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - workspace_/oauth2 + - 'workspace_/oauth2/{oauth2_credentials}' + - 'workspace_/oauth2/{oauth2_credentials}/consumer' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - workspace_/oauth2_tokens + - 'workspace_/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/credential' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/service' + - workspace_/openid-connect/issuers + - 'workspace_/openid-connect/issuers/{oic_issuers}' + - workspace_/openid-connect/jwks + - workspace_/plugins + - workspace_/plugins/enabled + - 'workspace_/plugins/schema/{name}' + - 'workspace_/plugins/{plugins}' + - 'workspace_/plugins/{plugins}/consumer' + - 'workspace_/plugins/{plugins}/consumer_group' + - 'workspace_/plugins/{plugins}/route' + - 'workspace_/plugins/{plugins}/service' + - workspace_/proxy-cache + - 'workspace_/proxy-cache/{cache_key}' + - 'workspace_/proxy-cache/{plugin_id}/caches/{cache_key}' + - workspace_/proxy-cache-advanced + - 'workspace_/proxy-cache-advanced/{cache_key}' + - 'workspace_/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/rbac/roles + - 'workspace_/rbac/roles/{rbac_roles}' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - 'workspace_/rbac/roles/{rbac_roles}/entities' + - 'workspace_/rbac/roles/{rbac_roles}/entities/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/entities/{entity_id}' + - 'workspace_/rbac/roles/{rbac_roles}/permissions' + - workspace_/rbac/users + - 'workspace_/rbac/users/{rbac_users}' + - 'workspace_/rbac/users/{rbac_users}/admins' + - 'workspace_/rbac/users/{rbac_users}/admins/{admins}' + - 'workspace_/rbac/users/{rbac_users}/developers' + - 'workspace_/rbac/users/{rbac_users}/developers/{developers}' + - 'workspace_/rbac/users/{rbac_users}/permissions' + - 'workspace_/rbac/users/{rbac_users}/roles' + - workspace_/routes + - 'workspace_/routes/{routes}' + - 'workspace_/routes/{routes}/filter-chains' + - 'workspace_/routes/{routes}/filter-chains/{filter_chains}' + - 'workspace_/routes/{routes}/filters/all' + - 'workspace_/routes/{routes}/filters/disabled' + - 'workspace_/routes/{routes}/filters/enabled' + - 'workspace_/routes/{routes}/plugins' + - 'workspace_/routes/{routes}/plugins/{plugins}' + - 'workspace_/routes/{routes}/service' + - workspace_/schemas/plugins/validate + - 'workspace_/schemas/plugins/{name}' + - 'workspace_/schemas/{db_entity_name}/validate' + - 'workspace_/schemas/{name}' + - workspace_/services + - 'workspace_/services/{services}' + - 'workspace_/services/{services}/application_instances' + - 'workspace_/services/{services}/application_instances/{application_instances}' + - 'workspace_/services/{services}/applications' + - 'workspace_/services/{services}/client_certificate' + - 'workspace_/services/{services}/degraphql/routes' + - 'workspace_/services/{services}/degraphql/routes/{degraphql_routes}' + - 'workspace_/services/{services}/degraphql_routes' + - 'workspace_/services/{services}/degraphql_routes/{degraphql_routes}' + - 'workspace_/services/{services}/document_objects' + - 'workspace_/services/{services}/document_objects/{document_objects}' + - 'workspace_/services/{services}/filter-chains' + - 'workspace_/services/{services}/filter-chains/{filter_chains}' + - 'workspace_/services/{services}/graphql-rate-limiting-advanced/costs' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/services/{services}/oauth2_tokens' + - 'workspace_/services/{services}/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/services/{services}/plugins' + - 'workspace_/services/{services}/plugins/{plugins}' + - 'workspace_/services/{services}/routes' + - 'workspace_/services/{services}/routes/{routes}' + - workspace_/sessions + - 'workspace_/sessions/{sessions}' + - workspace_/snis + - 'workspace_/snis/{snis}' + - 'workspace_/snis/{snis}/certificate' + - workspace_/status + - workspace_/tags + - 'workspace_/tags/{tags}' + - workspace_/targets + - 'workspace_/targets/{targets}' + - 'workspace_/targets/{targets}/upstream' + - workspace_/timers + - workspace_/upstreams + - 'workspace_/upstreams/{upstreams}' + - 'workspace_/upstreams/{upstreams}/client_certificate' + - 'workspace_/upstreams/{upstreams}/health' + - 'workspace_/upstreams/{upstreams}/targets' + - 'workspace_/upstreams/{upstreams}/targets/all' + - 'workspace_/upstreams/{upstreams}/targets/{targets}' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/unhealthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - workspace_/userinfo + - workspace_/vault-auth + - 'workspace_/vault-auth/{vault_auth_vaults}' + - 'workspace_/vault-auth/{vault}/credentials' + - 'workspace_/vault-auth/{vault}/credentials/token/{access_token}' + - 'workspace_/vault-auth/{vault}/credentials/{consumer}' + - workspace_/vaults + - 'workspace_/vaults/{vaults}' + - workspace_/vitals/ + - workspace_/vitals/cluster + - workspace_/vitals/cluster/status_codes + - 'workspace_/vitals/consumers/{consumer_id}/cluster' + - workspace_/vitals/nodes/ + - 'workspace_/vitals/nodes/{node_id}' + - 'workspace_/vitals/reports/{entity_type}' + - workspace_/vitals/status_code_classes + - workspace_/vitals/status_codes/by_consumer + - workspace_/vitals/status_codes/by_consumer_and_route + - workspace_/vitals/status_codes/by_route + - workspace_/vitals/status_codes/by_service + - workspace_/workspaces + - 'workspace_/workspaces/{workspaces}' + - 'workspace_/workspaces/{workspaces}/meta' + examples: + Get all endpoints: + value: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /admins + - /admins/password_resets + - /admins/register + - /admins/self/password + - /admins/self/token + - '/admins/{admins}' + - '/admins/{admins}/consumer' + - '/admins/{admins}/rbac_user' + - '/admins/{admin}/roles' + - '/admins/{admin}/workspaces' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumer_groups + - '/consumer_groups/{consumer_groups}' + - '/consumer_groups/{consumer_groups}/consumers' + - '/consumer_groups/{consumer_groups}/consumers/{consumers}' + - '/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - '/consumer_groups/{consumer_groups}/plugins' + - '/consumer_groups/{consumer_groups}/plugins/{plugins}' + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/consumer_groups' + - '/consumers/{consumers}/consumer_groups/{consumer_groups}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /developers + - /developers/export + - /developers/invite + - /developers/roles + - '/developers/roles/{rbac_roles}' + - '/developers/{developers}' + - '/developers/{developers}/applications' + - '/developers/{developers}/applications/{applications}' + - '/developers/{developers}/applications/{applications}/application_instances' + - '/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/consumer' + - '/developers/{developers}/credentials/{plugin}' + - '/developers/{developers}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/rbac_user' + - '/developers/{email_or_id}/plugins/' + - '/developers/{email_or_id}/plugins/{id}' + - /document_objects + - '/document_objects/{document_objects}' + - '/document_objects/{document_objects}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keyring + - /keyring/activate + - /keyring/active + - /keyring/export + - /keyring/generate + - /keyring/import + - /keyring/import/raw + - /keyring/recover + - /keyring/remove + - /keyring/vault/sync + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/consumer_group' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /rbac/roles + - '/rbac/roles/{rbac_roles}' + - '/rbac/roles/{rbac_roles}/endpoints' + - '/rbac/roles/{rbac_roles}/endpoints/permissions' + - '/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - '/rbac/roles/{rbac_roles}/entities' + - '/rbac/roles/{rbac_roles}/entities/permissions' + - '/rbac/roles/{rbac_roles}/entities/{entity_id}' + - '/rbac/roles/{rbac_roles}/permissions' + - /rbac/users + - '/rbac/users/{rbac_users}' + - '/rbac/users/{rbac_users}/admins' + - '/rbac/users/{rbac_users}/admins/{admins}' + - '/rbac/users/{rbac_users}/developers' + - '/rbac/users/{rbac_users}/developers/{developers}' + - '/rbac/users/{rbac_users}/permissions' + - '/rbac/users/{rbac_users}/roles' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/document_objects' + - '/services/{services}/document_objects/{document_objects}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + - /workspaces + - '/workspaces/{workspaces}' + - '/workspaces/{workspaces}/meta' + - '/{workspace_name}/kong' + - workspace_/acls + - 'workspace_/acls/{acls}' + - 'workspace_/acls/{acls}/consumer' + - workspace_/acme + - workspace_/acme/certificates + - 'workspace_/acme/certificates/{certificates}' + - workspace_/acme_storage + - 'workspace_/acme_storage/{acme_storage}' + - workspace_/admins + - workspace_/admins/password_resets + - workspace_/admins/register + - workspace_/admins/self/password + - workspace_/admins/self/token + - 'workspace_/admins/{admins}' + - 'workspace_/admins/{admins}/consumer' + - 'workspace_/admins/{admins}/rbac_user' + - 'workspace_/admins/{admin}/roles' + - 'workspace_/admins/{admin}/workspaces' + - workspace_/applications + - 'workspace_/applications/{applications}' + - 'workspace_/applications/{applications}/application_instances' + - 'workspace_/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/applications/{applications}/consumer' + - 'workspace_/applications/{applications}/credentials/{plugin}' + - 'workspace_/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/applications/{applications}/developer' + - workspace_/auth + - workspace_/basic-auths + - 'workspace_/basic-auths/{basicauth_credentials}' + - 'workspace_/basic-auths/{basicauth_credentials}/consumer' + - workspace_/ca_certificates + - 'workspace_/ca_certificates/{ca_certificates}' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - workspace_/cache + - 'workspace_/cache/{key}' + - workspace_/certificates + - 'workspace_/certificates/{certificates}' + - 'workspace_/certificates/{certificates}/services' + - 'workspace_/certificates/{certificates}/services/{services}' + - 'workspace_/certificates/{certificates}/snis' + - 'workspace_/certificates/{certificates}/snis/{snis}' + - 'workspace_/certificates/{certificates}/upstreams' + - 'workspace_/certificates/{certificates}/upstreams/{upstreams}' + - workspace_/clustering/data-planes + - workspace_/clustering/status + - workspace_/config + - workspace_/consumer_groups + - 'workspace_/consumer_groups/{consumer_groups}' + - 'workspace_/consumer_groups/{consumer_groups}/consumers' + - 'workspace_/consumer_groups/{consumer_groups}/consumers/{consumers}' + - 'workspace_/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - 'workspace_/consumer_groups/{consumer_groups}/plugins' + - 'workspace_/consumer_groups/{consumer_groups}/plugins/{plugins}' + - workspace_/consumers + - 'workspace_/consumers/{consumers}' + - 'workspace_/consumers/{consumers}/acls' + - 'workspace_/consumers/{consumers}/acls/{acls}' + - 'workspace_/consumers/{consumers}/admins' + - 'workspace_/consumers/{consumers}/admins/{admins}' + - 'workspace_/consumers/{consumers}/applications' + - 'workspace_/consumers/{consumers}/applications/{applications}' + - 'workspace_/consumers/{consumers}/basic-auth' + - 'workspace_/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - 'workspace_/consumers/{consumers}/consumer_groups' + - 'workspace_/consumers/{consumers}/consumer_groups/{consumer_groups}' + - 'workspace_/consumers/{consumers}/developers' + - 'workspace_/consumers/{consumers}/developers/{developers}' + - 'workspace_/consumers/{consumers}/hmac-auth' + - 'workspace_/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - 'workspace_/consumers/{consumers}/jwt' + - 'workspace_/consumers/{consumers}/jwt/{jwt_secrets}' + - 'workspace_/consumers/{consumers}/key-auth' + - 'workspace_/consumers/{consumers}/key-auth/{keyauth_credentials}' + - 'workspace_/consumers/{consumers}/key-auth-enc' + - 'workspace_/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - 'workspace_/consumers/{consumers}/login_attempts' + - 'workspace_/consumers/{consumers}/login_attempts/{login_attempts}' + - 'workspace_/consumers/{consumers}/mtls-auth' + - 'workspace_/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/oauth2' + - 'workspace_/consumers/{consumers}/oauth2/{oauth2_credentials}' + - 'workspace_/consumers/{consumers}/plugins' + - 'workspace_/consumers/{consumers}/plugins/{plugins}' + - 'workspace_/debug/cluster/log-level/{log_level}' + - workspace_/debug/node/log-level + - 'workspace_/debug/node/log-level/{log_level}' + - workspace_/debug/profiling/cpu + - workspace_/debug/profiling/gc-snapshot + - workspace_/debug/profiling/memory + - workspace_/degraphql_routes + - 'workspace_/degraphql_routes/{degraphql_routes}' + - 'workspace_/degraphql_routes/{degraphql_routes}/service' + - workspace_/developers + - workspace_/developers/export + - workspace_/developers/invite + - workspace_/developers/roles + - 'workspace_/developers/roles/{rbac_roles}' + - 'workspace_/developers/{developers}' + - 'workspace_/developers/{developers}/applications' + - 'workspace_/developers/{developers}/applications/{applications}' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/consumer' + - 'workspace_/developers/{developers}/credentials/{plugin}' + - 'workspace_/developers/{developers}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/rbac_user' + - 'workspace_/developers/{email_or_id}/plugins/' + - 'workspace_/developers/{email_or_id}/plugins/{id}' + - workspace_/document_objects + - 'workspace_/document_objects/{document_objects}' + - 'workspace_/document_objects/{document_objects}/service' + - workspace_/endpoints + - workspace_/entities/migrate + - workspace_/event-hooks + - workspace_/event-hooks/sources + - 'workspace_/event-hooks/sources/{source}' + - 'workspace_/event-hooks/sources/{source}/{event}' + - 'workspace_/event-hooks/{event_hooks}' + - 'workspace_/event-hooks/{event_hooks}/ping' + - 'workspace_/event-hooks/{event_hooks}/test' + - workspace_/files + - workspace_/files/* + - workspace_/files/partials/* + - 'workspace_/files/{files}' + - workspace_/filter-chains + - 'workspace_/filter-chains/{filter_chains}' + - 'workspace_/filter-chains/{filter_chains}/route' + - 'workspace_/filter-chains/{filter_chains}/service' + - workspace_/graphql-proxy-cache-advanced + - 'workspace_/graphql-proxy-cache-advanced/{cache_key}' + - 'workspace_/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/graphql-rate-limiting-advanced/costs + - 'workspace_/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - workspace_/graphql_ratelimiting_advanced_cost_decoration + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - workspace_/groups + - 'workspace_/groups/{groups}' + - 'workspace_/groups/{groups}/roles' + - workspace_/hmac-auths + - 'workspace_/hmac-auths/{hmacauth_credentials}' + - 'workspace_/hmac-auths/{hmacauth_credentials}/consumer' + - workspace_/jwt-signer/jwks + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}' + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - workspace_/jwts + - 'workspace_/jwts/{jwt_secrets}' + - 'workspace_/jwts/{jwt_secrets}/consumer' + - workspace_/key-auths + - 'workspace_/key-auths/{keyauth_credentials}' + - 'workspace_/key-auths/{keyauth_credentials}/consumer' + - workspace_/key-auths-enc + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}' + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}/consumer' + - workspace_/key-sets + - 'workspace_/key-sets/{key_sets}' + - 'workspace_/key-sets/{key_sets}/keys' + - 'workspace_/key-sets/{key_sets}/keys/{keys}' + - workspace_/keyring + - workspace_/keyring/activate + - workspace_/keyring/active + - workspace_/keyring/export + - workspace_/keyring/generate + - workspace_/keyring/import + - workspace_/keyring/import/raw + - workspace_/keyring/recover + - workspace_/keyring/remove + - workspace_/keyring/vault/sync + - workspace_/keys + - 'workspace_/keys/{keys}' + - 'workspace_/keys/{keys}/set' + - workspace_/konnect_applications + - 'workspace_/konnect_applications/{konnect_applications}' + - workspace_/license/report + - workspace_/licenses + - 'workspace_/licenses/{licenses}' + - workspace_/login_attempts + - 'workspace_/login_attempts/{login_attempts}' + - 'workspace_/login_attempts/{login_attempts}/consumer' + - workspace_/metrics + - workspace_/mtls-auths + - 'workspace_/mtls-auths/{mtls_auth_credentials}/consumer' + - workspace_/mtls_auth_credentials + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - workspace_/oauth2 + - 'workspace_/oauth2/{oauth2_credentials}' + - 'workspace_/oauth2/{oauth2_credentials}/consumer' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - workspace_/oauth2_tokens + - 'workspace_/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/credential' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/service' + - workspace_/openid-connect/issuers + - 'workspace_/openid-connect/issuers/{oic_issuers}' + - workspace_/openid-connect/jwks + - workspace_/plugins + - workspace_/plugins/enabled + - 'workspace_/plugins/schema/{name}' + - 'workspace_/plugins/{plugins}' + - 'workspace_/plugins/{plugins}/consumer' + - 'workspace_/plugins/{plugins}/consumer_group' + - 'workspace_/plugins/{plugins}/route' + - 'workspace_/plugins/{plugins}/service' + - workspace_/proxy-cache + - 'workspace_/proxy-cache/{cache_key}' + - 'workspace_/proxy-cache/{plugin_id}/caches/{cache_key}' + - workspace_/proxy-cache-advanced + - 'workspace_/proxy-cache-advanced/{cache_key}' + - 'workspace_/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/rbac/roles + - 'workspace_/rbac/roles/{rbac_roles}' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - 'workspace_/rbac/roles/{rbac_roles}/entities' + - 'workspace_/rbac/roles/{rbac_roles}/entities/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/entities/{entity_id}' + - 'workspace_/rbac/roles/{rbac_roles}/permissions' + - workspace_/rbac/users + - 'workspace_/rbac/users/{rbac_users}' + - 'workspace_/rbac/users/{rbac_users}/admins' + - 'workspace_/rbac/users/{rbac_users}/admins/{admins}' + - 'workspace_/rbac/users/{rbac_users}/developers' + - 'workspace_/rbac/users/{rbac_users}/developers/{developers}' + - 'workspace_/rbac/users/{rbac_users}/permissions' + - 'workspace_/rbac/users/{rbac_users}/roles' + - workspace_/routes + - 'workspace_/routes/{routes}' + - 'workspace_/routes/{routes}/filter-chains' + - 'workspace_/routes/{routes}/filter-chains/{filter_chains}' + - 'workspace_/routes/{routes}/filters/all' + - 'workspace_/routes/{routes}/filters/disabled' + - 'workspace_/routes/{routes}/filters/enabled' + - 'workspace_/routes/{routes}/plugins' + - 'workspace_/routes/{routes}/plugins/{plugins}' + - 'workspace_/routes/{routes}/service' + - workspace_/schemas/plugins/validate + - 'workspace_/schemas/plugins/{name}' + - 'workspace_/schemas/{db_entity_name}/validate' + - 'workspace_/schemas/{name}' + - workspace_/services + - 'workspace_/services/{services}' + - 'workspace_/services/{services}/application_instances' + - 'workspace_/services/{services}/application_instances/{application_instances}' + - 'workspace_/services/{services}/applications' + - 'workspace_/services/{services}/client_certificate' + - 'workspace_/services/{services}/degraphql/routes' + - 'workspace_/services/{services}/degraphql/routes/{degraphql_routes}' + - 'workspace_/services/{services}/degraphql_routes' + - 'workspace_/services/{services}/degraphql_routes/{degraphql_routes}' + - 'workspace_/services/{services}/document_objects' + - 'workspace_/services/{services}/document_objects/{document_objects}' + - 'workspace_/services/{services}/filter-chains' + - 'workspace_/services/{services}/filter-chains/{filter_chains}' + - 'workspace_/services/{services}/graphql-rate-limiting-advanced/costs' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/services/{services}/oauth2_tokens' + - 'workspace_/services/{services}/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/services/{services}/plugins' + - 'workspace_/services/{services}/plugins/{plugins}' + - 'workspace_/services/{services}/routes' + - 'workspace_/services/{services}/routes/{routes}' + - workspace_/sessions + - 'workspace_/sessions/{sessions}' + - workspace_/snis + - 'workspace_/snis/{snis}' + - 'workspace_/snis/{snis}/certificate' + - workspace_/status + - workspace_/tags + - 'workspace_/tags/{tags}' + - workspace_/targets + - 'workspace_/targets/{targets}' + - 'workspace_/targets/{targets}/upstream' + - workspace_/timers + - workspace_/upstreams + - 'workspace_/upstreams/{upstreams}' + - 'workspace_/upstreams/{upstreams}/client_certificate' + - 'workspace_/upstreams/{upstreams}/health' + - 'workspace_/upstreams/{upstreams}/targets' + - 'workspace_/upstreams/{upstreams}/targets/all' + - 'workspace_/upstreams/{upstreams}/targets/{targets}' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/unhealthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - workspace_/userinfo + - workspace_/vault-auth + - 'workspace_/vault-auth/{vault_auth_vaults}' + - 'workspace_/vault-auth/{vault}/credentials' + - 'workspace_/vault-auth/{vault}/credentials/token/{access_token}' + - 'workspace_/vault-auth/{vault}/credentials/{consumer}' + - workspace_/vaults + - 'workspace_/vaults/{vaults}' + - workspace_/vitals/ + - workspace_/vitals/cluster + - workspace_/vitals/cluster/status_codes + - 'workspace_/vitals/consumers/{consumer_id}/cluster' + - workspace_/vitals/nodes/ + - 'workspace_/vitals/nodes/{node_id}' + - 'workspace_/vitals/reports/{entity_type}' + - workspace_/vitals/status_code_classes + - workspace_/vitals/status_codes/by_consumer + - workspace_/vitals/status_codes/by_consumer_and_route + - workspace_/vitals/status_codes/by_route + - workspace_/vitals/status_codes/by_service + - workspace_/workspaces + - 'workspace_/workspaces/{workspaces}' + - 'workspace_/workspaces/{workspaces}/meta' + admins-response: + description: Example response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + status: 4 + username: test-admin + email: test@test.com + rbac_token_enabled: true + - created_at: 1556563122 + id: a93ff120-9e6c-4198-b47e-f779104c7eac + updated_at: 1556563122 + status: 0 + username: kong_admin + rbac_token_enabled: false + next: null + properties: + data: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + status: + type: integer + description: The status field indicates the state of the invitation. + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + next: + nullable: true + groups-response: + description: Example response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - created_at: 1717123483 + id: 4844ded2-06d1-44f5-974a-03982696f889 + updated_at: 1717123483 + name: group1 + comment: comment1 + - created_at: 1717123637 + id: 65b3d436-3c5b-4b0e-a2a5-ee188d526ad8 + updated_at: 1717123637 + name: group2 + comment: comment2 + next: null + properties: + data: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + name: + type: string + comment: + type: string + next: + nullable: true + rbac-user-response: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + enabled: + type: boolean + id: + type: string + name: + type: string + user_token: + type: string + user_token_ident: + type: string + next: + type: string + x-examples: + Example 1: + data: + - comment: null + created_at: 1557512629 + enabled: true + id: f035f120-a95e-4327-b2ae-8fa264601d75 + name: doc_lord + user_token: $2b$09$TIMneYcTosdG9WbzRsqcweAS2zote8g6I8HqXAtbFHR1pds2ymsh6 + user_token_ident: 88ea3 + - comment: null + created_at: 1557522650 + enabled: true + id: fa6881b2-f49f-4007-9475-577cd21d34f4 + name: doc_knight + user_token: $2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG + user_token_ident: 4d870 + next: null + examples: + Returned user: + value: + data: + - comment: null + created_at: 1557512629 + enabled: true + id: f035f120-a95e-4327-b2ae-8fa264601d75 + name: doc_lord + user_token: $2b$09$TIMneYcTosdG9WbzRsqcweAS2zote8g6I8HqXAtbFHR1pds2ymsh6 + user_token_ident: 88ea3 + - comment: null + created_at: 1557522650 + enabled: true + id: fa6881b2-f49f-4007-9475-577cd21d34f4 + name: doc_knight + user_token: $2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG + user_token_ident: 4d870 + next: null + audit-objects-response: + description: Example response generated for checking the `/status` endpoint without RBAC enabled. + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - client_ip: 127.0.0.1 + method: GET + path: /status + payload: null + rbac_user_id: null + rbac_user_name: null + removed_from_payload: null + request_id: OjOcUBvt6q6XJlX3dd6BSpy1uUkTyctC + request_source: null + request_timestamp: 1676424547 + signature: null + status: 200 + ttl: 2591997 + workspace: 1065b6d6-219f-4002-b3e9-334fc3eff46c + total: 1 + properties: + data: + type: array + description: The client IP address + items: + type: object + properties: + client_ip: + type: string + description: The client IP address + method: + type: string + description: The HTTP method + path: + type: string + description: The path of the endpoint + payload: + nullable: true + rbac_user_id: + nullable: true + rbac_user_name: + nullable: true + removed_from_payload: + nullable: true + request_id: + type: string + request_source: + nullable: true + request_timestamp: + type: integer + signature: + nullable: true + status: + type: integer + ttl: + type: integer + workspace: + type: string + total: + type: integer + database-audit-log-response: + description: Example response for a consumer creation log entry + content: + application/json: + schema: + properties: + id: + type: string + event-hooks-response: + description: Example event hooks response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + config: + type: object + properties: + body: + type: string + body_format: + type: boolean + headers: + type: object + properties: + content-type: + type: string + headers_format: + type: boolean + method: + type: string + payload: + type: object + properties: + text: + type: string + payload_format: + type: boolean + secret: + type: string + ssl_verify: + type: boolean + url: + type: string + functions: + type: array + items: + type: string + created_at: + type: integer + event: + type: string + handler: + type: string + id: + type: string + on_change: + type: string + snooze: + type: integer + source: + type: string + next: + type: string + x-examples: + Example 1: + data: + - config: + body: null + body_format: true + headers: + content-type: application/json + headers_format: false + method: POST + payload: + text: payload_text + payload_format: true + secret: null + ssl_verify: false + url: 'https://hooks.slack.com/services/foo/bar/baz' + created_at: 1627588552 + event: admins + handler: webhook-custom + id: 937df175-3db2-4e6d-8aa1-d95c94a76089 + on_change: null + snooze: null + source: crud + - config: + headers: {} + secret: null + ssl_verify: false + url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + created_at: 1627581575 + event: consumers + handler: webhook + id: c57340ab-9fed-40fd-bb7e-1cef8d37c2df + on_change: null + snooze: null + source: crud + - config: + functions: + - | + return function (data, event, source, pid) + local user = data.entity.username + error("Event hook on consumer " .. user .. "") + end + created_at: 1627595513 + event: consumers + handler: lambda + id: c9fdd58d-5416-4d3a-9467-51e5cfe4ca0e + on_change: null + snooze: null + source: crud + next: null + examples: + Example event hooks response: + value: + data: + - config: + body: "null" + body_format: true + headers: + content-type: string + headers_format: true + method: string + payload: + text: string + payload_format: true + secret: "null" + ssl_verify: true + url: string + functions: + - string + created_at: 0 + event: string + handler: string + id: string + on_change: "string" + snooze: 0 + source: string + next: "null" + event-hooks-request: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + event: + description: A string describing the Kong entity the event hook listens to for events. + type: object + properties: + type: + type: string + description: + type: string + handler: + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + type: object + properties: + type: + type: string + description: + type: string + source: + type: object + description: A string describing the action that triggers the event hook. + properties: + type: + type: string + description: + type: string + snooze: + type: object + description: An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + properties: + type: + type: string + description: + type: string + on_change: + type: object + description: An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + properties: + type: + type: string + description: + type: string + config.url: + type: object + description: The URL the JSON POST request is made to with the event data as the payload. + properties: + type: + type: string + description: + type: string + config.method: + type: object + description: The HTTP method used to create the custom webhook. + properties: + type: + type: string + description: + type: string + config.payload: + type: object + description: An object that includes key/value pairs that describe the configurable payload body. Supports templating. The full list of available template parameters can be found in the `/sources` API output, under the `fields` JSON object. + properties: + type: + type: string + description: + type: string + config.payload_format: + type: object + properties: + type: + type: string + description: A optional boolean (defaults to true) indicating whether to format the `config.payload` with resty templating. When set to false, the payload is sent as a raw object. + description: + type: string + config.body: + type: object + properties: + type: + type: string + description: + type: string + config.body_format: + type: object + properties: + type: + type: string + description: + type: string + config.headers: + type: object + properties: + type: + type: string + description: + type: string + config.headers_format: + type: object + properties: + type: + type: string + description: + type: string + config.secret: + type: object + properties: + type: + type: string + description: + type: string + config.ssl_verify: + type: object + properties: + type: + type: string + description: + type: string + x-examples: + Example 1: + data: + event: + type: string + description: A string describing the Kong entity the event hook listens to for events. (optional) + handler: + type: string + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. (required) + source: + type: string + description: A string describing the action that triggers the event 'https://hooks.slack.com/services/foo/bar/baz' + requried: true + snooze: + type: integer + description: An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + on_change: + type: boolean + description: An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + config.url: + type: string + description: The URL the JSON POST request is made to with the event data as the payloads. + required: true + config.method: + type: string + description: The HTTP method used to create the custom webhook. + required: true + config.payload: + type: object + description: An object that includes key/value pairs that describe the configurable payload body. Supports templating. + config.payload_format: + type: boolean + description: An optional boolean indicating whether to format the config.payload with resty templating. When set to false, the payload is sent as a raw object. + default: true + config.body: + type: string + description: An optional string sent in the remote request. + config.body_format: + type: boolean + description: An optional boolean indicating whether to format `config.body` with resty templating. When set to false, the body is sent as a raw object. + default: true + config.headers: + type: object + description: An object defining additional HTTP headers to send in the webhook request. + config.headers_format: + type: boolean + description: An optional boolean indicating whether to format `config.headers` with resty templating. When set to true, the `config.headers` value is treated as a template. + default: false + config.secret: + type: string + description: An optional string used to sign the remote webhook for remote verification. When set, Kong signs the body of the event hook with HMAC-SHA1 and includes it in a header, `x-kong-signature`, sent to the remote endpoint. (optional) + config.ssl_verify: + type: boolean + description: A boolean indicating whether to verify the SSL certificate of the remote HTTPS server where the event hook will be sent. + default: false + ping-event-hook: + description: Example response + content: + application/json: + schema: + type: object + properties: + source: + type: string + event_hooks: + type: object + properties: + source: + type: string + id: + type: string + on_change: + type: string + event: + type: string + handler: + type: string + created_at: + type: integer + config: + type: object + properties: + headers: + type: object + properties: + content-type: + type: string + ssl_verify: + type: boolean + url: + type: string + secret: + type: string + snooze: + type: string + event: + type: string + x-examples: + Example 1: + source: 'kong:event_hooks' + event_hooks: + source: crud + id: c57340ab-9fed-40fd-bb7e-1cef8d37c2df + on_change: null + event: consumers + handler: webhook + created_at: 1627581575 + config: + headers: + content-type: application/json + ssl_verify: false + url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + secret: null + snooze: null + event: ping + examples: + Pinged event hook: + value: + source: 'kong:event_hooks' + event_hooks: + source: crud + id: c57340ab-9fed-40fd-bb7e-1cef8d37c2df + on_change: "string" + event: consumers + handler: webhook + created_at: 1627581575 + config: + headers: + content-type: application/json + ssl_verify: false + url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + secret: "secret" + snooze: "null" + event: ping + requestBodies: + vault-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + prefix: env + name: env + description: This vault is used to retrieve Redis database access credentials. + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + properties: + prefix: + type: string + description: | + The unique prefix (or identifier) for this vault configuration. Use this prefix to load the right vault configuration and implementation when referencing secrets with the other entities. + example: env + name: + type: string + description: | + The name of the vault that's being added. The vault implementation must be installed in every Kong instance. + example: env + description: + type: string + description: | + The description of the vault object. + example: This vault is used to retrieve Redis database access credentials. + config: + type: object + description: | + The configuration properties for the vault, which can be found on the vaults' documentation page. + properties: + prefix: + type: string + example: SSL_ + tags: + type: array + description: | + An optional set of strings associated with the vault, used for grouping and filtering. + items: + type: string + examples: + Example 1: + value: + prefix: env + name: env + description: This vault is used to retrieve Redis database access credentials. + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + description: The request object for creating a new vault object. + target-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + properties: + upstream: + type: object + description: | + The unique identifier or the name of the upstream for which to update the target. + properties: + id: + type: string + example: 173a6cee-90d1-40a7-89cf-0329eca780a6 + description: The unique identifier or the name of the upstream for which to update the target. + weight: + default: 100 + description: The weight this target gets within the upstream load balancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + minimum: 0 + maximum: 65535 + tags: + type: array + description: An optional set of strings associated with the target for grouping and filtering. + items: + type: string + examples: + Example: + value: + upstream: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + weight: 100 + tags: + - string + description: The request body for creating a new target entity. + upstream-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + - x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + properties: + name: + type: string + description: This is a hostname, which must be equal to the `host` of a service. + example: my-upstream + algorithm: + type: string + description: | + Which load balancing algorithm to use. + enum: + - consistent-hashing + - least-connections + - round-robin + - latency + default: round-robin + example: round-robin + hash_on: + type: string + description: What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + hash_fallback: + type: string + description: What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no Consumer identified). Not available if hash_on is set to cookie. + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + example: none + hash_on_header: + type: string + description: The header name to take the value from as hash input. Only required when `hash_on` is set to header. + example: none + hash_fallback_header: + type: string + description: The header name to take the value from as hash input. Only required when hash_fallback is set to header. + default: none + example: none + hash_on_cookie: + type: string + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + example: none + hash_on_cookie_path: + type: string + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + default: / + example: / + hash_on_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + example: hash_value + hash_fallback_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + example: hash_value + hash_on_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + example: hash_value + hash_fallback_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + example: hash_value + slots: + type: integer + description: The number of slots in the load balancer algorithm. If the algorithm is set to `round-robin`, this setting determines the maximum number of slots. If the algorithm is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range 10-65536. + minimum: 10 + maximum: 65536 + default: 10000 + example: 5000 + healthchecks: + type: object + properties: + passive: + type: object + properties: + type: + type: string + description: Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, http and https options are equivalent. Accepted values are `tcp`, `http`, `https`, `grpc`, `grpcs`. + default: http + enum: + - tcp + - http + - https + - grpc + - grpcs + example: tcp + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=201`. With JSON, use an array. + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + example: + - 200 + - 201 + - 202 + items: + type: integer + enum: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: + type: integer + description: Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks. + default: 0 + example: 2 + unhealthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an array. + default: + - 429 + - 500 + - 503 + example: + - 500 + - 503 + items: + type: integer + enum: + - 429 + - 500 + - 503 + timeouts: + type: integer + description: Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + http_failures: + type: integer + description: Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 3 + tcp_failures: + type: integer + description: Number of TCP connection failures to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + active: + type: object + properties: + https_verify_certificate: + type: boolean + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an array. + default: + - 200 + - 302 + example: + - 200 + - 201 + items: + type: integer + successes: + type: integer + description: Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. + default: 0 + example: 3 + interval: + type: integer + description: Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. + default: 0 + example: 30 + unhealthy: + type: object + properties: + http_failures: + type: integer + description: Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. + default: 0 + example: 2 + http_statuses: + type: array + description: An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=404`. With JSON, use an array. + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + example: + - 400 + - 404 + items: + type: integer + timeouts: + type: integer + description: Number of timeouts in active probes to consider a target unhealthy. + default: 0 + example: 2 + tcp_failures: + type: integer + description: Number of TCP failures in active probes to consider a target unhealthy. + default: 0 + example: 1 + interval: + type: integer + description: Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. + default: 0 + example: 10 + type: + type: string + description: Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. + enum: + - tcp + - http + - https + - grpc + - grpcs + default: http + example: https + concurrency: + type: integer + description: Number of targets to check concurrently in active health checks. + default: 10 + example: 5 + headers: + type: object + description: One or more lists of values indexed by header name to use in GET HTTP request to run as a probe on active health checks. Values must be pre-formatted. + example: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: + type: integer + description: Socket timeout for active health checks (in seconds). + default: 1 + example: 5 + http_path: + type: string + description: Path to use in GET HTTP request to run as a probe on active health checks. + default: / + https_sni: + type: string + description: The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. This is particularly useful when Targets are configured using IPs, so that the target host's certificate can be verified with the proper SNI. + threshold: + type: integer + description: The minimum percentage of the upstream's targets' weight that must be available for the whole upstream to be considered healthy. + minimum: 0 + maximum: 100 + default: 0 + tags: + type: array + description: An optional set of strings associated with the Upstream for grouping and filtering. + example: + - user-level + - low-priority + items: + type: string + host_header: + type: string + description: The hostname to be used as Host header when proxying requests through Kong. + client_certificate: + type: object + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + example: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: + type: boolean + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host. + example: false + required: + - name + examples: + Upstream: + value: + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + Example request: + value: + name: my-upstream + tags: + - user-level + - low-priority + algorithm: round-robin + description: The request object for creating a new upstream. + service-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + properties: + name: + type: string + description: | + The service name. + example: my-service + retries: + type: integer + description: | + The number of retries to execute upon failure to proxy. Default:`5`. + default: 5 + example: 5 + protocol: + type: string + description: |- + The protocol used to communicate with the upstream. Accepted values are: "`grpc`", "`grpcs`", "`http`", "`https`", "`tcp`", "`tls`", "`tls_passthrough`", "`udp`", "`ws`" + , "`wss`" + . Default: "`http`". + default: http + enum: + - grpc + - grpcs + - http + - https + - tcp + - 'tls ' + - tls_passthrough + - udp + - ws + - wss + example: http + host: + type: string + description: | + The host of the upstream server. Note that the host value is case sensitive. + example: example.com + port: + type: integer + description: | + The upstream server port. Default: `80`. + default: 80 + example: 80 + path: + type: string + description: | + The path to be used in requests to the upstream server. + example: /some_api + connect_timeout: + type: integer + description: The timeout in milliseconds for establishing a connection to the upstream server. Default `60000`. + default: 6000 + example: 6000 + write_timeout: + type: integer + description: | + The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + read_timeout: + type: integer + description: | + The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + tags: + type: array + description: | + An optional set of strings associated with the service for grouping and filtering. + items: + type: string + example: user-level + client_certificate: + type: object + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is `client_certificate.id=`. With JSON, use `"client_certificate":{"id":""}`. + properties: + id: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: + type: boolean + description: | + Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected. + default: true + tls_verify_depth: + type: string + description: | + Maximum depth of chain while verifying Upstream server's TLS certificate. If set to null, then the Nginx default is respected. Default: null. + example: respected + default: null + nullable: true + ca_certificates: + type: array + description: Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream servers TLS certificate. If set to null when Nginx default is respected. With form-encoded, the notation is `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`. With JSON, use an array. + items: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: + type: boolean + default: true + description: Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). + required: + - protocol + - host + - port + - enabled + examples: + Example: + value: + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 6000 + write_timeout: 6000 + read_timeout: 6000 + tags: + - user-level + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: true + description: The request body for creating a new service entity. + route-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + snis: + - foo.test + - example.com + sources: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + destinations: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + properties: + name: + type: string + description: | + The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test". + protocols: + type: array + description: An array of the protocols this route should allow + items: + type: string + default: https + example: tcp + methods: + type: array + description: | + A list of HTTP methods that match this route. + items: + type: string + example: GET + hosts: + type: array + description: A list of domain names that match this route. Note that the hosts value is case sensitive. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array. + items: + type: string + paths: + type: array + description: A list of paths that match this route. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an array. The path can be a regular expression, or a plain text pattern. + items: + type: string + headers: + type: object + description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The Host header cannot be used with this attribute hosts should be specified using the `hosts` attribute. When headers contains only one value and that value starts with the special prefix` ~*`, the value is interpreted as a regular expression. + properties: + x-my-header: + type: array + items: + type: string + x-another-header: + type: array + items: + type: string + https_redirect_status_code: + type: integer + description: |- + The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS` + Location header is injected by Kong if the field is set to `301`, `302`, `307` or `308`. Note: This config applies only if the route is configured to only accept the https protocol. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`. + default: 426 + enum: + - 426 + - 301 + - 302 + - 307 + - 308 + example: 426 + regex_priority: + type: integer + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + default: 0 + example: 0 + strip_path: + type: boolean + description: When matching a route via one of the paths, strip the matching prefix from the upstream request URL. + default: true + path_handling: + type: string + description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. Accepted values are "`v0`", "`v1`". + enum: + - v1 + - v0 + example: v0 + preserve_host: + type: boolean + description: When matching a route via one of the `hosts` domain names, use the request `host` header in the upstream request headers. If set to `false`, the upstream Host header will be that of the service's host. + default: true + request_buffering: + type: boolean + default: true + description: | + Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true. + response_buffering: + type: boolean + default: true + description: | + Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: `true`. + snis: + type: array + description: | + A list of SNIs that match this route when using stream routing. + items: + type: string + sources: + type: array + description: | + A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 10.1.0.0/16 + port: + type: integer + example: 1234 + destinations: + type: array + description: | + A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 0.1.0.0/16 + port: + type: integer + tags: + type: array + description: | + An optional set of strings associated with the route for grouping and filtering. + items: + type: string + service: + type: object + description: The service this route is associated to. This is where the route proxies traffic to. With form-encoded, the notation is service.id= or service.name=. With JSON, use `"service":{"id":""}` or `"service":{"name":""}`. + nullable: true + properties: + id: + type: string + example: af8330d3-dbdc-48bd-b1be-55b98608834b + required: + - protocols + - https_redirect_status_code + - preserve_host + - request_buffering + - response_buffering + examples: + Create a route: + value: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + description: Route request body + keys-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + properties: + set: + type: object + description: The id (an UUID) of the key-set with which to associate the key .With form-encoded, the notation is `set.id=` or `set.name=`. With JSON, use `"set":{"id":""}` or `"set":{"name":""}.` + properties: + id: + type: string + description: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: + type: string + example: my-key + description: | + The name to associate with the given keys. + kid: + type: string + description: | + A unique identifier for a key. + example: '42' + jwk: + type: string + description: A JSON Web Key represented as a string. + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + pem: + type: object + description: | + A keypair in PEM format. + properties: + private_key: + type: string + example: 'private_key": "-----BEGIN' + public_key: + type: string + example: 'public_key": "-----BEGIN' + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + required: + - kid + description: The request body for creating a new key entity. + key-set-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-key_set + tags: + - google-keys + - mozilla-keys + properties: + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + description: The request body for creating a new key-set entity. + plugin-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: rate-limiting + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + properties: + name: + type: string + description: The name of the plugin that's being added. The plugin must be installed in every Kong instance separately. + example: rate-limiting + route: + type: string + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default `null`.With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique within a workspace for Kong Gateway Enterprise. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the plugin for grouping and filtering. + items: + type: string + ordering: + type: object + description: | + Describes a dependency to another plugin to determine plugin ordering during the access phase. + - `before`: The plugin will be executed before a specified plugin or list of plugins. + - `after`: The plugin will be executed after a specified plugin or list of plugins. + properties: + before: + type: array + items: + type: string + examples: + request example: + value: + name: rate-limiting + route: string + service: string + consumer: string + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 500 + protocols: + - http + enabled: true + tags: + - string + ordering: + before: + - string + description: Plugin request body + consumer-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + username: + type: string + description: | + The unique username of the Consumer. You must send either this field or custom_id with the request. + custom_id: + type: string + 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. + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + required: + - username + - custom_id + description: Consumer request body + create-sni: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-sni + tags: + - user-level + - low-priority + certificate: + id: a2e013e8-7623-4494-a347-6d29108ff68b + properties: + name: + type: string + description: The SNI name to associate with the given certificate. + example: my-sni + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + example: '["user-level", "low-priority"]' + certificate: + type: object + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is `certificate.id=`. With JSON, use `"certificate":{"id":""}`. + properties: + id: + type: string + example: 91020192-062d-416f-a275-9addeeaffaf2 + description: 91020192-062d-416f-a275-9addeeaffaf2 + required: + - name + - certificate + description: A JSON object containing the details of the new SNI, including the name, certificate, and tags. + cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example: + id: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + key: '-----BEGIN RSA PRIVATE KEY-----...' + cert_alt: '-----BEGIN CERTIFICATE-----...' + key_alt: '-----BEGIN EC PRIVATE KEY-----...' + snis: + - foo.test + - example.com + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: PEM-encoded public certificate chain of the SSL key pair. + example: '-----BEGIN CERTIFICATE-----...' + key: + type: string + example: '-----BEGIN RSA PRIVATE KEY-----...' + description: PEM-encoded private key of the SSL key pair. + cert_alt: + type: string + description: PEM-encoded public certificate chain of the alternate SSL key pair. + key_alt: + type: string + description: PEM-encoded private key of the alternate SSL key pair. + example: '"-----BEGIN EC PRIVATE KEY-----..."' + snis: + type: array + description: An array of zero or more hostnames to associate with this certificate as SNIs. + items: + type: string + tags: + type: array + description: | + An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + passphrase: + type: string + description: To load an encrypted private key into Kong, specify the passphrase using this attributKong will decrypt the private key and store it in its database. e. Enterprise Only + example: example + required: + - cert + - key + description: The certificate request body + CA-cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: | + PEM-encoded public certificate of the CA. + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + description: | + SHA256 hex digest of the public certificate. + tags: + type: array + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + required: + - cert + description: This request body represents a new Certificate Authority (CA) certificate and includes the properties required to create a new certificate. + consumer_group_request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + created_at: 1557522650 + id: fa6881b2-f49f-4007-9475-577cd21d34f4 + name: JL + tags: + - tag1 + - tag2 + properties: + name: + type: string + description: A unique name for the consumer group you want to create. + example: my_group + tags: + type: array + description: An optional set of strings associated with the consumer group for grouping and filtering. + items: + type: string + required: + - name + examples: + example consumer group request body: + value: + name: my_group + tags: + - string + description: The consumer groups request body for creating new consumer groups. + license-request: + content: + application/json: + schema: + type: object + properties: + payload: + type: string + description: | + The Kong Gateway license in JSON format. + example: '{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}' + description: The request body for uploading a license. + workspace-request: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: | + The workspace name. + example: my-workspace + description: | + The workspace object describes the workspace entity, which has an ID and a name. + rbac-request: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + description: | + The RBAC user name. + user_token: + type: string + + description: The authentication token to be presented to the Admin API. The value will be hashed and cannot be fetched in plaintext. + enabled: + type: string + + description: | + A flag to enable or disable the user. By default, users are enabled. + comment: + type: string + + description: | + A string describing the RBAC user object. + filter-chains-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: my-chain + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + - name: go-rate-limiting + enabled: true + config: '{ "minute": 30 }' + - name: rust-response-transformer + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: + - my-tag + properties: + ' name': + type: string + + description: | + The name of the filter chain. + example: my-chain + enabled: + type: string + + description: | + Whether the filter chain is applied. Default: true. + route: + type: string + + description: | + The route to which this chain is applied. + A filter chain must be applied to either a single route or a single service. + Default: `null`. + + In form-encoded format, the notation is `route.id=` or `route.name=`. + In JSON format, use `"route":{"id":""}` or `"route":{"name":""}`. + service: + type: string + + description: | + The service to which this chain is applied. + A filter chain must be applied to either a single route or a single service. Default: `null`. + + In form-encoded format, the notation is `service.id=` or `service.name=`. + In JSON format, use `"service":{"id":""}` or `"service":{"name":""}`. + example: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + type: string + + description: An array of filter definitions. Each filter is an object containing a mandatory name, an optional config, and a boolean enabled setting. + tags: + type: string + + description: | + An optional set of strings associated with the filter chain for grouping and filtering. + examples: + Example 1: + value: + ' name': my-chain + enabled: string + route: string + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: string + tags: string + description: A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + add-webhook: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: consumers + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: webhook + source: + type: string + + description: | + A string describing the action that triggers the event hook. + example: crud + snooze: + type: integer + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + example: 0 + default: 0 + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + config.url: + type: string + + description: | + The URL the JSON POST request is made to with the event data as the payload. + example: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + config.headers: + type: object + + description: | + An object defining additional HTTP headers to send in the webhook request. For example `{"X-Custom-Header": "My Value"}`. + properties: + headers: + type: string + + description: | + Optional configuration header + config.secret: + type: string + + description: | + An optional string used to sign the remote webhook for remote verification. When set, Kong signs the body of the event hook with HMAC-SHA1 and includes it in a header, `x-kong-signature`, sent to the remote endpoint. + config.ssl_verify: + type: string + + description: | + A boolean indicating whether to verify the SSL certificate of the remote HTTPS server where the event hook will be sent. The default is false. + required: + - handler + - source + - config.url + examples: + Example 2: + value: + event: consumers + handler: webhook + source: crud + snooze: 0 + on_change: true + config.url: 'https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6' + config.headers: + headers: string + config.secret: string + config.ssl_verify: string + description: Request body for adding a webhook + add-custom-webhook: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: admins + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: webhook-custom + source: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: crud + snooze: + type: integer + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + default: 1 + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + default: true + config.url: + type: string + + description: | + The URL the JSON POST request is made to with the event data as the payload. + example: 'https://hooks.slack.com/services/foo/bar/baz' + config.method: + type: string + + description: | + The HTTP method used to create the custom webhook. + example: GET + config.payload: + type: object + + description: | + An object that includes key/value pairs that describe the configurable payload body. Supports templating. The full list of available template parameters can be found in the /sources API output, under the fields JSON object. + properties: + text: + type: string + + description: Configuration payload + config.payload_format: + type: boolean + + description: | + A optional boolean (defaults to true) indicating whether to format `config.payload` with resty templating. When set to false, the payload is sent as a raw object. + config.body: + type: string + + description: | + An optional string sent in the remote request. + config.body_format: + type: boolean + + description: | + An optional boolean (defaults to true) indicating whether to format `config.body` with resty templating. When set to false, the body is sent as a raw object. To see all the available parameters defined for a specific source, check the source fields displayed by the `/event-hooks/source` endpoint. + config.headers: + type: object + + description: | + An object defining additional HTTP headers to send in the webhook request. For example `{"Content-type": "application/json", "X-Custom-Header": "My Value"}`. + config.headers_format: + type: string + + description: | + An optional boolean (defaults to false) indicating whether to format `config.headers` with resty templating. When set to true, the `config.headers` value is treated as a template. To see all the available parameters defined for a specific source, check the source fields displayed by the `/event-hooks/sources` endpoint. + config.secret: + type: string + + description: | + An optional string used to sign the remote webhook for remote verification. When set, Kong signs the body of the event hook with HMAC-SHA1 and includes it in a header, `x-kong-signature`, to the remote endpoint. + config.ssl_verify: + type: boolean + + required: + - handler + - source + - config.url + - config.method + description: Request body for adding a custom webhook + add-log: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: routes + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: log + source: + type: string + + description: | + A string describing the action that triggers the event hook. + example: crud + snooze: + type: integer + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + required: + - handler + - source + examples: + Example log request: + value: + event: routes + handler: log + source: crud + snooze: 0 + on_change: true + description: Add a log event hook request body + lambda-event-hook: + content: + application/json: + schema: + type: object + properties: + event: + type: string + + description: | + A string describing the Kong entity the event hook listens to for events. + example: consumers + handler: + type: string + + description: | + A string describing one of four handler options: webhook, webhook-custom, log, or lambda. + example: lambda + source: + type: string + + description: | + A string describing the action that triggers the event hook. + example: crud + snooze: + type: boolean + + description: | + An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. + on_change: + type: boolean + + description: | + An optional boolean indicating whether to trigger an event when key parts of a payload have changed. + config.functions: + type: array + + description: | + An array of Lua code functions to execute on the event hook. + items: + + type: string + example: '"functions": [ "return function (data, event, source, pid)\n local user = data.entity.username\n error(\"Event hook on consumer \" .. user .. \"\")\nend\n" ]' + required: + - handler + - source + - config.functions + examples: + lambda-event-hook: + value: + event: consumers + handler: lambda + source: crud + snooze: true + on_change: true + config.functions: + - '"functions": [ "return function (data, event, source, pid)\n local user = data.entity.username\n error(\"Event hook on consumer \" .. user .. \"\")\nend\n" ]' + description: Request body for adding a lambda event hook + securitySchemes: + kongAdminToken: + type: apiKey + in: header + name: Kong-Admin-Token + description: | + When RBAC is enabled, an admin token is required to use the Kong Admin API. + This token is passed in a `Kong-Admin-Token` header by default. + To configure the header name, adjust `rbac_auth_header` in `kong.conf`. +

+ Each admin has their own token. + The admin associated with the token must have relevant permissions for the object they're interacting with. + Generate tokens using the `/admins` API. +

+ If RBAC isn't enabled, this token isn't required. + +externalDocs: + description: Kong Gateway Enterprise Admin API + url: 'https://docs.konghq.com' +info: + contact: + email: docs@konghq.com + name: Kong Inc + url: 'https://konghq.com' + description: |- + OpenAPI 3.0 spec for Kong Gateway's Enterprise Admin API. + + You can learn more about Kong Gateway at [docs.konghq.com](https://docs.konghq.com) + .Give Kong a star at [Kong/kong](https://github.com/kong/kong) repository. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + title: Enterprise Kong Admin API + version: 3.8.0 +openapi: 3.0.0 +paths: + /: + get: + summary: Get Kong's instance information + tags: + - Information + operationId: geInfo + description: | + Returns detailed information about the Kong gateway instance, including the full Kong configuration, available and unavailable plugins, version, edition (enterprise or community), a tagline, the unique node identifier, and other metadata. + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + version: + type: string + description: The version number of the Kong instance. + example: "2.3.3" + edition: + type: string + description: Indicates whether the Kong instance is the Community or Enterprise edition. + example: "enterprise" + tagline: + type: string + description: A tagline or slogan for the Kong instance. + example: "Welcome to Kong" + node_id: + type: string + description: A unique identifier for the node, in UUID format. + format: uuid + example: "a74d7c4f-ef83-4bbe-a5e7-3f5409f4a0b9" + hostname: + type: string + description: The hostname of the Kong node. + example: "kong-node.example.com" + timers: + type: object + description: Information about running and pending timers. + properties: + running: + type: integer + description: The number of running timers. + example: 5 + pending: + type: integer + description: The number of pending timers. + example: 2 + plugins: + type: object + description: Information about plugins. + properties: + available_on_server: + type: object + additionalProperties: + type: object + properties: + version: + type: string + description: The version of the plugin. + priority: + type: integer + description: The priority of the plugin. + enabled_in_cluster: + type: array + items: + type: string + description: A list of distinct plugin names enabled in the cluster. + example: ["jwt", "acl"] + lua_version: + type: string + description: The version of Lua used by the Kong instance. + example: "LuaJIT 2.1.0-beta3" + configuration: + type: object + description: A sanitized version of the Kong configuration, excluding sensitive values. + additionalProperties: true + pids: + type: object + description: Process IDs for the master process and worker processes. + properties: + master: + type: integer + description: The PID of the master process. + example: 4321 + workers: + type: array + items: + type: integer + description: An array of worker process PIDs. + example: [1234, 5678] + examples: + fullExample: + summary: Example response + value: + configuration: + _debug_pg_ttl_cleanup_interval: 300 + admin_acc_logs: "/usr/local/kong/logs/admin_access.log" + admin_access_log: "/dev/stdout" + admin_approved_email: "true" + admin_emails_from: "\"\"" + admin_error_log: "/dev/stderr" + admin_gui_access_log: "logs/admin_gui_access.log" + admin_gui_auth_header: "******" + admin_gui_auth_login_attempts: 0 + admin_gui_error_log: "logs/admin_gui_error.log" + admin_gui_flags: "{}" + admin_gui_listen: + - "0.0.0.0:8002" + - "0.0.0.0:8445 ssl" + admin_gui_origin: "http://localhost:8002" + edition: "enterprise" + hostname: "8a487998603b" + lua_version: "LuaJIT 2.1.0-20231117" + node_id: "1f257156-5e44-46e2-a618-767f5c7529e3" + pids: + master: 1 + workers: + - 2382 + - 2383 + plugins: + available_on_server: + acl: true + acme: true + disabled_on_server: + application-registration: true + enabled_in_cluster: [] + tagline: "Welcome to kong" + timers: + pending: 1 + running: 1128 + version: "3.6.0.0" + '401': + $ref: '#/components/responses/HTTP401Error' + '405': + description: Method Not Allowed + content: + application/json: + schema: + $ref: '#/components/schemas/UnauthorizedError' + headers: + Server: + description: Kong's server tokens. + schema: + type: string + example: "kong/2.3.3" + /ca_certificates: + get: + description: Retrieve a list of all available Certificate Authority (CA) certificates, including the certificate ID, creation date, and other details. You can use query parameters to filter the results by size or tags, for example `/ca-certificates?size=50&tags=enterprise`. + operationId: list-ca_certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: A successful response listing CA Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all CA Certificates + tags: + - CA Certificates + post: + description: Create a new Certificate Authority (CA) certificate. The request body must include the `cert` property, the certificate data in PEM format; it can also include `cert_digest`, a digest of the certificate in hex format for verifying the certificates integrity, and `tags`, an optional list of tags to categorize the certificate. + operationId: create-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully created CA Certificate + '400': + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + cert: 'invalid certificate: x509.new: asn1/a_d2i_fp.c:197:error:0D06B08E:asn1 encoding routines:asn1_d2i_read_bio:not enough data' + message: 'schema violation (cert: invalid certificate: x509.new: asn1/a_d2i_fp.c:197:error:0D06B08E:asn1 encoding routines:asn1_d2i_read_bio:not enough data)' + name: schema violation + code: 2 + properties: + fields: + type: object + properties: + cert: + type: string + description: Error information about the certificate. + example: 'invalid certificate: x509.new:' + message: + type: string + description: More information about the error + example: 'schema violation (cert: invalid certificate: x509.new:' + name: + type: string + description: The name of the error. + example: schema violation + code: + type: integer + description: An error code. + example: 2 + examples: + invalid certificate: + value: + fields: + cert: 'invalid certificate: x509.new:' + message: 'schema violation (cert: invalid certificate: x509.new:' + name: schema violation + code: 2 + description: 400 Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + '/ca_certificates/{ca_certificate_id}': + delete: + description: Delete the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. + operationId: delete-ca_certificate + responses: + '204': + description: Successfully deleted CA Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a CA Certificate + tags: + - CA Certificates + get: + description: Retrieve details about the specified Certificate Authority (CA) certificate using the provided path parameter `ca_certificate_id`. + operationId: get-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully fetched CA Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a CA Certificate + tags: + - CA Certificates + patch: + description: Update a CA Certificate + operationId: update-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully updated CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + put: + description: Update the specified Certificate Authority (CA) certificate using the provided `ca_certificate_id`. Use this endpoint to modify an existing CA certificate in the system. The request body should include the fields of the CA certificate that need to be updated. + operationId: upsert-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully upserted CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '404': + description: Not Found + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + parameters: + - $ref: '#/components/parameters/ca_certificate_id' + /certificates: + get: + description: Retrieve a list of all available CA Certificate Authority (CA) certificates. You can use query parameters to filter the results by size or tags, for example `/certificates?size=50&tags=enterprise`. + operationId: list-certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + examples: + Certificate: + value: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + description: A successful response listing Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Certificates + tags: + - Certificates + post: + description: Create a new certificate with the provided details. Use this endpoint to add a new certificate to the system. The request body must include the certificate data and other details required for creating a new certificate. + operationId: create-certificate + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Description of the new Certificate for creation + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + key: 'invalid key: pkey.new:load_key: pem/pem_lib.c:949:error:09091064:PEM routines:PEM_read_bio_ex:bad base64 decode' + cert: 'invalid certificate: x509.new: asn1/tasn_dec.c:309:error:0D07803A:asn1 encoding routines:asn1_item_embed_d2i:nested asn1 error' + message: '2 schema violations (cert: invalid certificate: x509.new: asn1/tasn_dec.c:309:error:0D07803A:asn1 encoding routines:asn1_item_embed_d2i:nested asn1 error; key: invalid key: pkey.new:load_key: pem/pem_lib.c:949:error:09091064:PEM routines:PEM_read_bio_ex:bad base64 decode)' + name: schema violation + code: 2 + properties: + fields: + type: object + properties: + key: + type: string + description: Information about the key. + example: 'invalid key: pkey.new:load_key: ' + cert: + type: string + description: Information about the certificate. + example: 'invalid certificate: x509.new: ' + message: + type: string + description: error message + example: '2 schema violations (cert: invalid certificate: x509.new: asn1/tasn_dec.c:309:error:0D07803A:asn1' + name: + type: string + description: The name of the error message. + example: schema violation + code: + type: integer + description: An error code. + example: 2 + examples: + Example 1: + value: + fields: + key: string + cert: string + message: string + name: string + code: 0 + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Certificate + tags: + - Certificates + '/certificates/{certificate_id}': + delete: + description: Delete a Certificate + operationId: delete-certificate + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Certificate + tags: + - Certificates + get: + description: Get a Certificate using ID. + operationId: get-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully fetched Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Certificate + tags: + - Certificates + patch: + description: | + Update a Certificate + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + operationId: update-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + put: + description: | + Update details about the specified certificate using the provided path parameter `certificate_id`. + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + operationId: upsert-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/certificate_id' + '/certificates/{certificate_name_or_id}/snis': + get: + description: Retrieve a paginated list of all SNIs associated with a certificate. Use this endpoint to retrieve a list of SNIs that are linked to a specific certificate. You can use the optional query parameters to filter the results based on specific criteria. The response will include the list of SNIs and pagination information. See the response schema for details on the expected format of the response body. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/SNI' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing SNIs + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs associated with a Certificate + tags: + - SNIs + operationId: list-sni-with-certificate + post: + description: Create a new SNI and associate it with a certificate in the system. Use this endpoint to add a new SNI to the system and link it to a specific certificate. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully created SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI associated with a Certificate + tags: + - SNIs + operationId: create-sni-with-certificate + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + '/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: | + Delete a an SNI associated with a Certificate using ID or name. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a an SNI associated with a Certificate + tags: + - SNIs + operationId: delete-sni-with-cert + get: + description: Get an SNI associated with a Certificate using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully fetched SNI + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch an SNI associated with a Certificate + tags: + - SNIs + operationId: fetch-sni-with-cert + patch: + description: Update an existing SNI associated with a certificate in the system using the SNI ID or name. The request body should include the fields of the SNI that need to be updated, such as the name, description, or other properties. If the request body contains valid data, the endpoint will update the SNI and return a success response. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully updated SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a an SNI associated with a Certificate + tags: + - SNIs + operationId: update-sni-with-cert + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: | + Create or Update an SNI associated with a Certificate using ID or name. + + Inserts (or replaces) the SNI under the requested resource with the definition specified in the body. The SNI will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the SNI being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new SNI without specifying id (neither in the URL nor in the body), then it will be auto-generated. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully upserted SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert an SNI associated with a Certificate + tags: + - SNIs + operationId: upsert-sni-with-cert + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/certificate_id' + - $ref: '#/components/parameters/sni_name_or_id' + /consumers: + get: + description: Retrieve a list of all consumers.You can use query parameters to filter the results by size or tags, for example `/consumers?size=50&tags=enterprise`. + operationId: list-consumer + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + summary: List all Consumers + tags: + - Consumers + post: + description: Create a new Consumer + operationId: create-consumer + responses: + '201': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '409': + description: Conflict + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + username: stri22ng + message: UNIQUE violation detected on `{username="stri22ng"}` + name: unique constraint violation + code: 5 + properties: + fields: + type: object + description: An array of fields that may have caused the error. + properties: + username: + type: string + description: The username that triggerd the conflict. + example: stri22ng + message: + type: string + description: Detail about the conflict. + example: UNIQUE violation detected on `{username=\"stri22ng\"}` + name: + type: string + description: THe name of the violation. + example: unique constraint violation + code: + type: integer + description: Error code for debugging purposes. + example: 5 + examples: + Constraint violation: + value: + fields: + username: stri22ng + message: UNIQUE violation detected on `{username="stri22ng"}` + name: unique constraint violation + code: 5 + summary: Create a new Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + '/consumers/{consumer_username_or_id}': + delete: + description: Delete a Consumer + operationId: delete-consumer + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Consumer + tags: + - Consumers + get: + description: | + Retrieve the details of a specific consumer in the system using either the consumer ID or the consumer username. If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: get-consumer + responses: + '200': + $ref: '#/components/responses/consumer_response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a consumer + tags: + - Consumers + patch: + description: | + Update the details of a specific consumer in the system using either the consumer ID or the consumer username.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: update-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully updated Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: |- + Create or Update Consumer using ID or username. The consumer will be identified via the username or id attribute.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + + When the username or id attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its id. Otherwise it will be identified by its username. + + When creating a new Consumer without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a username in the URL and a different one in the request body is not allowed. + operationId: upsert-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully upserted Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a consumer + tags: + - Plugins + operationId: list-plugins-with-consumer + post: + description: Create a new plugin associated with a Consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a consumer + tags: + - Plugins + operationId: create-plugin-for-consumer + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_name_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a aconsumer using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a consumer + tags: + - Plugins + operationId: delete-plugin-for-consumer + get: + description: Get a plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '404': + description: Not Found + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: Not found + properties: + message: + type: string + example: Not Found + description: 404 Not Found + examples: + Not Found: + value: + message: Not Found + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a plugin associated with a Consumer + tags: + - Plugins + operationId: fetch-plugin-with-consumer + patch: + description: Update a plugin associated with a consumer using the consumer username or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a consumer + tags: + - Plugins + operationId: update-plugin-with-consumer + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update a plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-customer + parameters: + - $ref: '#/components/parameters/consumer_name_or_id' + - $ref: '#/components/parameters/plugin_id' + /key-sets: + get: + description: | + Retrieve a list of all Key-sets in the system. A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. Key Sets can be both tagged and filtered by tags. + operationId: list-key-set + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Key-sets + tags: + - Key-sets + post: + description: | + This endpoint allows creating a new Key-set by sending a JSON object that describes the Key-set to be created.The request body must contain all the fields required to create a new Key-set. + operationId: create-key-set + responses: + '201': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '409': + description: Conflict + content: + application/json: + schema: + type: object + properties: + fields: + type: object + properties: + name: + type: string + message: + type: string + name: + type: string + code: + type: integer + x-examples: + Example 1: + fields: + name: my-key_set + message: UNIQUE violation detected on `{name="my-key_set"}` + name: unique constraint violation + code: 5 + examples: + Not Found: + value: + fields: + name: my-key_set + message: UNIQUE violation detected on `{name="my-key_set"}` + name: unique constraint violation + code: 5 + summary: Create a new Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + '/key-sets/{key-set_id_or_name}': + delete: + description: Delete a Key-set + operationId: delete-key-set + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key-set + tags: + - Key-sets + get: + description: | + Get a Key-set using ID or name. This endpoint retrieves information about a specific key-set based on its ID or name. + operationId: get-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Key-set + tags: + - Key-sets + patch: + description: |- + Update a Key-set using ID or name. + + Note: This API is not available in DB-less mode. + + Inserts (or replaces) the Key Set under the requested resource with the definition specified in the body. The Key Set will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the Key Set being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new Key Set without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + operationId: update-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: | + Update a Key-set using ID or name. + operationId: upsert-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/key-set_id_or_name' + /keys: + get: + description: List all Keys + operationId: list-key + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Key' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Keys + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Keys + tags: + - Keys + post: + description: This API endpoint allows you to create a new key. When the request is successful, the API will respond with a 200 status code and a JSON object that represents the newly created key. If the request is invalid, the API will respond with a 400 status code and an error message in the response body. + operationId: create-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + '/keys/{key_id_or_name}': + delete: + description: Delete a Key + operationId: delete-key + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + summary: Delete a Key + tags: + - Keys + get: + description: Get a Key using ID or name. + operationId: get-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully fetched Key + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Key + tags: + - Keys + patch: + description: Update a Key + operationId: update-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: | + Create or update a key using ID or name. + operationId: upsert-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/key_id_or_name' + /plugins: + get: + description: | + List all plugins + + operationId: list-plugin + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins + tags: + - Plugins + post: + description: Create a new plugin + operationId: create-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + '/plugins/{plugin_id}': + delete: + description: Delete a plugin + operationId: delete-plugin + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin + tags: + - Plugins + get: + description: Get a plugin using ID. + operationId: get-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a plugin + tags: + - Plugins + patch: + description: Update a plugin + operationId: update-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update plugin using ID. + operationId: upsert-plugin + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/plugin_id' + /routes: + get: + description: |- + List all routes + + route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to its associated service. + + Note: Path handling algorithms v1 was deprecated in Kong 3.0. From Kong 3.0, when router_flavor is set to expressions, route.path_handling will be unconfigurable and the path handling behavior will be "v0"; when router_flavor is set to traditional_compatible, the path handling behavior will be "v0" regardless of the value of route.path_handling. Only router_flavor = traditional will support path_handling "v1' behavior. + operationId: list-route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes + tags: + - Routes + post: + description: Create a new route + operationId: create-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + '/routes/{route_id_or_name}': + delete: + description: Delete a route + operationId: delete-route + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route + tags: + - Routes + get: + description: Get a route using ID or name. + operationId: get-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route + tags: + - Routes + patch: + description: Update a route + operationId: update-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: Create or update a route using ID or name. + operationId: upsert-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins': + get: + description: List all plugins associated with a route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a route + tags: + - Plugins + operationId: list-plugins-with-route + post: + description: Create a new plugin associated with a route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a route using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a route + tags: + - Plugins + operationId: delete-plugin-with-route + get: + description: Get a plugin associated with a route using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a route + tags: + - Plugins + operationId: fetch-plugin-with-route + patch: + description: Update a plugin associated with a route using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-route + put: + description: Create or Update a plugin associated with a route using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + /services: + get: + description: List all Services + operationId: list-service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Service' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Services + '401': + $ref: '#/components/responses/HTTP401Error' + + summary: List all services + tags: + - Services + post: + description: Create a new service + operationId: create-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + '/services/{service_id_or_name}': + delete: + description: Delete a Service + operationId: delete-service + responses: + '204': + description: Successfully deleted Service or the resource didn't exist + summary: Delete a Service + tags: + - Services + get: + description: Get a Service using ID or name. + operationId: get-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched Service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Service + tags: + - Services + patch: + description: Update a Service + operationId: update-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update Service using ID or name. + operationId: upsert-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins': + get: + description: List all plugins associated with a Service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + summary: List all plugins associated with a Service + tags: + - Plugins + operationId: list-plugins-with-service + post: + description: Create a new plugin associated with a Service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a Service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a Service using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + summary: Delete a plugin associated with a Service + tags: + - Plugins + operationId: delete-plugin-with-service + get: + description: Get a plugin associated with a Service using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a Service + tags: + - Plugins + operationId: fetch-plugin-with-service + patch: + description: Update a plugin associated with a Service using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a Service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-service + put: + description: Create or Update a plugin associated with a Service using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a Service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes associated with a Service + tags: + - Routes + operationId: list-routes-with-service + post: + description: Create a new route associated with a Service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route associated with a Service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a Service using ID or name. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route associated with a Service + tags: + - Routes + operationId: delete-route-with-service + get: + description: Get a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route associated with a Service + tags: + - Routes + operationId: fetch-route-with-service + patch: + description: Update a route associated with a Service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route associated with a Service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-with-service + put: + description: Create or Update a route associated with a Service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route associated with a Service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-with-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + /snis: + get: + description: List all SNIs + operationId: list-sni + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs + tags: + - SNIs + post: + description: Create a new SNI + operationId: create-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + '/snis/{sni_name_or_id}': + delete: + description: Delete an SNI + operationId: delete-sni + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an SNI + tags: + - SNIs + get: + description: Get an SNI using ID or name. + operationId: get-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI + tags: + - SNIs + patch: + description: Update an SNI + operationId: update-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name. + operationId: upsert-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/sni_name_or_id' + /upstreams: + get: + description: | + List all registered upstreams. You can filter the results by pagination size, offset, or tags like /upstreams?size=10&offset=0. + operationId: list-upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Upstreams + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Upstreams + tags: + - Upstreams + post: + description: Create a new Upstream + operationId: create-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + '/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream + operationId: delete-upstream + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an Upstream + tags: + - Upstreams + get: + description: Get an Upstream using ID or name. + operationId: get-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an Upstream + tags: + - Upstreams + patch: + description: Update an Upstream + operationId: update-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name. + operationId: upsert-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Target' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Targets + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Targets associated with an Upstream + tags: + - Targets + operationId: list-target-with-upstream + post: + description: Create a new Target associated with an Upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-with-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + summary: Delete a Target associated with a an Upstream + tags: + - Targets + operationId: delete-target-with-upstream + get: + description: Get a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream + tags: + - Targets + operationId: fetch-target-with-upstream + patch: + description: Update a Target associated with a an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Target associated with a an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-with-upstream + put: + description: Create or Update a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-with-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + /vaults: + get: + description: List all Vaults + operationId: list-vault + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Vaults + tags: + - Vaults + post: + description: Create a new Vault + operationId: create-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + '/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault + operationId: delete-vault + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Vault + tags: + - Vaults + get: + description: | + Fetch a Vault using ID or prefix. + + Vault entities are used to configure different Vault connectors. + operationId: get-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Vault + tags: + - Vaults + patch: + description: Update a Vault + operationId: update-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix. + operationId: upsert-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/vault_id_or_prefix' + /workspaces: + get: + description: |- + List all Workspaces + + For workspace use cases and configuration examples, see [Workspace examples](https://docs.konghq.com/gateway/latest/kong-enterprise/workspaces/). This endpoint will only return workspaces that the current user has access to. + operationId: list-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Workspace' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Workspaces + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Workspaces + tags: + - Workspaces + post: + description: | + Create a new Workspace + + For workspace use cases and configuration examples, see [Workspace examples](https://docs.konghq.com/gateway/3.2.x/kong-enterprise/workspaces/). + operationId: create-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Description of the new Workspace for creation + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully created Workspace + '400': + content: + application/json: + schema: + type: object + description: Invalid Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Workspace + tags: + - Workspaces + '/workspaces/{workspace_id_or_name}': + delete: + description: Delete a Workspace + operationId: delete-workspace + responses: + '204': + description: Successfully deleted Workspace or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Workspace + tags: + - Workspaces + parameters: + - schema: + type: boolean + example: true + in: query + name: cascade + description: The `cascade` option lets you delete a workspace and all of its entities in one request. + get: + description: Get a Workspace using ID or name. + operationId: get-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully fetched Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Workspace + tags: + - Workspaces + patch: + description: Update a Workspace + operationId: update-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Fields of the Workspace that need to be updated + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully updated Workspace + '400': + content: + application/json: + schema: + type: object + description: Invalid Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Workspace + tags: + - Workspaces + put: + description: Create or Update Workspace using ID or name. + operationId: upsert-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Description of the Workspace + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + description: Successfully upserted Workspace + '400': + content: + application/json: + schema: + type: object + description: Invalid Workspace + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Workspace + tags: + - Workspaces + parameters: + - $ref: '#/components/parameters/workspace_id_or_name' + '/{workspace}/certificates': + get: + description: List all Certificates in a workspace + operationId: list-certificate-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Certificate' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Certificates in a workspace + tags: + - Certificates + post: + description: Create a new Certificate in a workspace + operationId: create-certificate-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Certificate in a workspace + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/certificates/{certificate_id}': + delete: + description: Delete a Certificate in a workspace + operationId: delete-certificate-in-workspace + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Certificate in a workspace + tags: + - Certificates + get: + description: Get a Certificate using ID in a workspace. + operationId: get-certificate-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully fetched Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Certificate in a workspace + tags: + - Certificates + patch: + description: Update a Certificate in a workspace + operationId: update-certificate-in-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Fields of the Certificate that need to be updated + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Certificate in a workspace + tags: + - Certificates + put: + description: Create or Update Certificate using ID in a workspace. + operationId: upsert-certificate-in-workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Description of the Certificate + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Certificate in a workspace + tags: + - Certificates + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/certificate_id' + '/{workspace}/certificates/{certificate_id}/snis': + get: + description: List all SNIs associated with a Certificate in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs associated with a Certificate in a workspace + tags: + - SNIs + operationId: list-sni-with-cert-in-workspace + post: + description: Create a new SNI associated with a Certificate in a workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI associated with a Certificate in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: create-sni-with-cert-in-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/certificate_id' + '/{workspace}/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: Delete a an SNI associated with a Certificate using ID or name in a workspace. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + summary: Delete an SNI associated with a Certificate in a workspace + tags: + - SNIs + operationId: delete-sni-with-cert-in-workspace + get: + description: Get an SNI associated with a Certificate using ID or name in a workspace. + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI associated with a Certificate in a workspace + tags: + - SNIs + operationId: fetch-sni-with-cert-in-workspace + patch: + description: Update a an SNI associated with a Certificate using ID or name in a workspace. + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI associated with a Certificate in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: update-sni-with-cert-in-workspace + put: + description: Create or Update an SNI associated with a Certificate using ID or name in a workspace. + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert an SNI associated with a Certificate in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: upsert-sni-with-cert-in-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/certificate_id' + - $ref: '#/components/parameters/sni_name_or_id' + '/{workspace}/consumers': + get: + description: List all Consumers in a workspace + operationId: list-consumer-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Consumers in a workspace + tags: + - Consumers + post: + description: Create a new Consumer in a workspace + operationId: create-consumer-in-workspace + parameters: + - description: Name or ID of workspace + example: team-a + in: path + name: workspace + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Consumer in a workspace + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/consumers/{consumer_username_or_id}': + delete: + description: Delete a Consumer in a workspace + operationId: delete-consumer-in-workspace + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Consumer in a workspace + tags: + - Consumers + get: + description: Get a Consumer using ID or username in a workspace. + operationId: get-consumer-in-workspace + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Consumer in a workspace + tags: + - Consumers + patch: + description: Update a Consumer in a workspace + operationId: update-consumer-in-workspace + responses: + '200': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Consumer in a workspace + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: Create or Update Consumer using ID or username in a workspace. + operationId: upsert-consumer-in-workspace + responses: + '200': + $ref: '#/components/responses/consumer_response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Consumer in a workspace + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + '/{workspace}/consumers/{consumer_username_or_id}/plugins': + get: + description: List all plugins associated with a Consumer in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a Consumer in a workspace + tags: + - Plugins + operationId: list-plugins-consumer-workspace + post: + description: Create a new plugin associated with a Consumer in a workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a Consumer in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-consumer-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + '/{workspace}/consumers/{consumer_username_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a Consumer using ID in a workspace. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a Consumer in a workspace + tags: + - Plugins + operationId: delete-plugin-with-consumer-workspace + get: + description: Get a plugin associated with a Consumer using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a plugin associated with a Consumer in a workspace + tags: + - Plugins + operationId: fetch-plugin-with-consumer-workspace + patch: + description: Update a plugin associated with a Consumer using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a Consumer in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-consumer-workspace + put: + description: Create or Update a plugin associated with a Consumer using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-consumer-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/key-sets': + get: + description: List all Key-sets in a workspace + operationId: list-key-set-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Key-sets in a workspace + tags: + - Key-sets + post: + description: Create a new Key-set in a workspace + operationId: create-key-set-in-workspace + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key-set in a workspace + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/key-sets/{key-set_id_or_name}': + delete: + description: Delete a Key-set in a workspace + operationId: delete-key-set-in-workspace + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key-set in a workspace + tags: + - Key-sets + get: + description: Get a Key-set using ID or name in a workspace. + operationId: get-key-set-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key-set' + description: Successfully fetched Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Key-set in a workspace + tags: + - Key-sets + patch: + description: Update a Key-set in a workspace + operationId: update-key-set-in-workspace + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key-set in a workspace + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: Create or Update Key-set using ID or name in a workspace. + operationId: upsert-key-set-in-workspace + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key-set in a workspace + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/key-set_id_or_name' + '/{workspace}/keys': + get: + description: List all Keys in a workspace + operationId: list-key-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example 1: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Keys in a workspace + tags: + - Keys + post: + description: Create a new Key in a workspace + operationId: create-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Successfully created Key: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key in a workspace + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/keys/{key_id_or_name}': + delete: + description: Delete a Key in a workspace + operationId: delete-key-in-workspace + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key in a workspace + tags: + - Keys + get: + description: Get a Key using ID or name in a workspace. + operationId: get-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example 1: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully fetched Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Key in a workspace + tags: + - Keys + patch: + description: Update a Key in a workspace + operationId: update-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key in a workspace + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: Create or Update Key using ID or name in a workspace. + operationId: upsert-key-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example 1: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key in a workspace + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/key_id_or_name' + '/{workspace}/plugins': + get: + description: List all plugins in a workspace + operationId: list-plugin-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + summary: List all plugins in a workspace + tags: + - Plugins + post: + description: Create a new plugin in a workspace + operationId: create-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/plugins/{plugin_id}': + delete: + description: Delete a plugin in a workspace + operationId: delete-plugin-in-workspace + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + summary: Delete a plugin in a workspace + tags: + - Plugins + get: + description: Get a plugin using ID in a workspace. + operationId: get-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin in a workspace + tags: + - Plugins + patch: + description: Update a plugin in a workspace + operationId: update-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update plugin using ID in a workspace. + operationId: upsert-plugin-in-workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/routes': + get: + description: List all routes in a workspace + operationId: list-route-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes in a workspace + tags: + - Routes + post: + description: Create a new route in a workspace + operationId: create-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route in a workspace + tags: + - Routes + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/routes/{route_id_or_name}': + delete: + description: Delete a route in a workspace + operationId: delete-route-in-workspace + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route in a workspace + tags: + - Routes + get: + description: Get a route using ID or name in a workspace. + operationId: get-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route in a workspace + tags: + - Routes + patch: + description: Update a route in a workspace + operationId: update-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: Create or Update route using ID or name in a workspace. + operationId: upsert-route-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/route_id_or_name' + '/{workspace}/routes/{route_id_or_name}/plugins': + get: + description: List all plugins associated with a route in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a route in a workspace + tags: + - Plugins + operationId: list-plugins-with-route-workspace + post: + description: Create a new plugin associated with a route in a workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a route in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-route-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/route_id_or_name' + '/{workspace}/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a route using ID in a workspace. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a route in a workspace + tags: + - Plugins + operationId: delete-plugin-with-route-workspace + get: + description: Get a plugin associated with a route using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a route in a workspace + tags: + - Plugins + operationId: fetch-plugin-with-route-workspace + patch: + description: Update a plugin associated with a route using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a route in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-route-workspace + put: + description: Create or Update a plugin associated with a route using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a route in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-route-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/services': + get: + description: List all Services in a workspace + operationId: list-service-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: A successful response listing Services + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Services in a workspace + tags: + - Services + post: + description: Create a new Service in a workspace + operationId: create-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Service in a workspace + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/services/{service_id_or_name}': + delete: + description: Delete a Service in a workspace + operationId: delete-service-in-workspace + responses: + '204': + description: Successfully deleted Service or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Service in a workspace + tags: + - Services + get: + description: Get a Service using ID or name in a workspace. + operationId: get-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched Service + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Service in a workspace + tags: + - Services + patch: + description: Update a Service in a workspace + operationId: update-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Service in a workspace + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update Service using ID or name in a workspace. + operationId: upsert-service-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted Service + '400': + content: + application/json: + schema: + type: object + description: Invalid Service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Service in a workspace + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + '/{workspace}/services/{service_id_or_name}/plugins': + get: + description: List all plugins associated with a Service in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: List all plugins associated with a Service in a workspace + tags: + - Plugins + operationId: list-plugins-with-service-workspace + post: + description: Create a new plugin associated with a Service in a workspace + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a Service in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + '/{workspace}/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a Service using ID in a workspace. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + summary: Delete a plugin associated with a Service in a workspace + tags: + - Plugins + operationId: delete-plugin-with-service-workspace + get: + description: Get a plugin associated with a Service using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a plugin associated with a Service in a workspace + tags: + - Plugins + operationId: fetch-plugin-with-service-workspace + patch: + description: Update a plugin associated with a Service using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a Service in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-with-service-workspace + put: + description: Create or Update a plugin associated with a Service using ID in a workspace. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Service in a workspace + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a Service in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: A successful response listing routes + summary: List all routes associated with a Service in a workspace + tags: + - Routes + operationId: list-routes-with-service-workspace + post: + description: Create a new route associated with a Service in a workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route associated with a Service in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + '/{workspace}/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a Service using ID or name in a workspace. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route associated with a Service in a workspace + tags: + - Routes + operationId: delete-route-with-service-workspace + get: + description: Get a route associated with a Service using ID or name in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route associated with a Service in a workspace + tags: + - Routes + operationId: fetch-route-with-service-workspace + patch: + description: Update a route associated with a Service using ID or name in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route associated with a Service in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-with-service-workspace + put: + description: Create or Update a route associated with a Service using ID or name in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route associated with a Service in a workspace + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-with-service-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + '/{workspace}/snis': + get: + description: List all SNIs in a workspace + operationId: list-sni-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs in a workspace + tags: + - SNIs + post: + description: Create a new SNI in a workspace + operationId: create-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/snis/{sni_name_or_id}': + delete: + description: Delete an SNI in a workspace + operationId: delete-sni-in-workspace + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an SNI in a workspace + tags: + - SNIs + get: + description: Get an SNI using ID or name in a workspace. + operationId: get-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI in a workspace + tags: + - SNIs + patch: + description: Update an SNI in a workspace + operationId: update-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name in a workspace. + operationId: upsert-sni-in-workspace + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a SNI in a workspace + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/sni_name_or_id' + '/{workspace}/upstreams': + get: + description: List all Upstreams in a workspace + operationId: list-upstream-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Upstreams + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Upstreams in a workspace + tags: + - Upstreams + post: + description: Create a new Upstream in a workspace + operationId: create-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Upstream in a workspace + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream in a workspace + operationId: delete-upstream-in-workspace + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an Upstream in a workspace + tags: + - Upstreams + get: + description: Get an Upstream using ID or name in a workspace. + operationId: get-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an Upstream in a workspace + tags: + - Upstreams + patch: + description: Update an Upstream in a workspace + operationId: update-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an Upstream in a workspace + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name in a workspace. + operationId: upsert-upstream-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Upstream in a workspace + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/upstream_id_or_name' + '/{workspace}/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream in a workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: A successful response listing Targets + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Targets associated with an Upstream in a workspace + tags: + - Targets + operationId: list-targets-with-upstream-workspace + post: + description: Create a new Target associated with an Upstream in a workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Target associated with an Upstream in a workspace + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-with-upstream-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/upstream_id_or_name' + '/{workspace}/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target in a workspace. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Target associated with a an Upstream in a workspace + tags: + - Targets + operationId: delete-target-with-upstream-workspace + get: + description: Get a Target associated with an Upstream using ID or target in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream in a workspace + tags: + - Targets + operationId: fetch-target-with-upstream-workspace + patch: + description: Update a Target associated with a an Upstream using ID or target in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Target associated with a an Upstream in a workspace + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-with-upstream-workspace + put: + description: Create or Update a Target associated with an Upstream using ID or target in a workspace. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Target associated with an Upstream in a workspace + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-with-upstream-workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + '/{workspace}/vaults': + get: + description: List all Vaults in a workspace + operationId: list-vault-in-workspace + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Vaults in a workspace + tags: + - Vaults + post: + description: Create a new Vault in a workspace + operationId: create-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Vault in a workspace + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/workspace' + '/{workspace}/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault in a workspace + operationId: delete-vault-in-workspace + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + summary: Delete a Vault in a workspace + tags: + - Vaults + get: + description: Get a Vault using ID or prefix in a workspace. + operationId: get-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Vault in a workspace + tags: + - Vaults + patch: + description: Update a Vault in a workspace + operationId: update-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Vault in a workspace + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix in a workspace. + operationId: upsert-vault-in-workspace + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Vault in a workspace + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/vault_id_or_prefix' + /consumer_groups: + get: + summary: List consumer groups + tags: + - consumer_groups + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups + description: | + List all consumer groups + + Use consumer groups to manage consumer affiliation. + post: + summary: Create a consumer group + operationId: post-consumer_groups + responses: + '201': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a new consumer group. + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List a specific consumer group + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups-group_name + description: Returns a consumer group by passing either the `group_name` or `group_id` as a path parameter. + tags: + - consumer_groups + put: + summary: Create consumer group + operationId: put-consumer_groups-group_name_or_id + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a consumer group by passing a new group name as the path parameter + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + delete: + summary: Delete a consumer group + operationId: delete-consumer_groups-group_name_or_id + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a consumer group. Deleting a consumer group removes all consumers from that group. This operation does not delete existing consuemrs. + tags: + - consumer_groups + '/consumers/{consumer_username_or_id}/consumer_groups': + parameters: + - $ref: '#/components/parameters/Gatewayapi_Consumer_username_or_id' + get: + summary: List consumer groups for a consumer + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumers-consumer_name_or_id-consumer_groups + description: | + View all consumer groups that a consumer is assigned to. + tags: + - consumer_groups + parameters: + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-size' + post: + summary: Add a consumer to a specific consumer group. + operationId: post-consumers-consumer_username_or_id-consumer_groups + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + requestBody: + content: + application/json: + schema: + type: object + properties: + group: + type: string + description: | + The name or ID of the group to add the consumer to. + example: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + required: + - group + examples: + Example request body: + value: + group: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + description: The request body contains the group ID for the group that you are adding a consumer into. + tags: + - consumer_groups + delete: + summary: Remove a consumer from all groups + operationId: delete-consumers-consumer_username_or_id-consumer_groups + responses: + '204': + description: | + HTTP/1.1 204 No Content + description: Remove a consumer from all groups. + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}/consumers': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List all consumers in a consumer group + tags: + - consumer_groups + operationId: get-consumer_groups-group_name_or_id-consumers + description: List all consumers in a consumer group + parameters: + - $ref: '#/components/parameters/Gatewayapi_Pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + post: + summary: Add a consumer to a group + operationId: post-consumer_groups-group_name_or_id-consumers + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + tags: + - consumer_groups + requestBody: + content: + application/json: + schema: + type: object + properties: + consumer: + type: string + description: | + The name or ID of the consumer to add to this group. + example: 8a4bba3c-7f82-45f0-8121-ed4d2847c4a4 + delete: + summary: Remove all consumers from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes all consumers from a specified consumer group. + tags: + - consumer_groups + '/consumers/{consumer_name_or_id}/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/consumer_name_or_id' + - $ref: '#/components/parameters/group_name_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumers-consumer_name_or_id-consumer_groups-group_name_or_id + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes a consumer from a consumer group. This operation does not delete the consumer group. + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}/consumers/{consumer_username_or_id}': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + - $ref: '#/components/parameters/consumer_username_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers-consumer_name_or_id + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: The consumer groups endpoint for removing a consumer from a specified consumer group. + tags: + - consumer_groups + '/consumer_groups/{group_name_or_id}/overrides/plugins/rate-limiting-advanced': + parameters: + - $ref: '#/components/parameters/group_name_or_id' + put: + summary: Configure rate limiting for a consumer group. + operationId: put-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + x-examples: + Example 1: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + properties: + config: + type: object + properties: + limit: + type: array + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + retry_after_jitter_max: + type: integer + description: | + The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + window_size: + type: array + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + example: sliding + group: + type: string + description: The consumer group + example: test-group + plugin: + type: string + description: The name of the plugin + example: rate-limiting-advanced + examples: + 'Example ': + value: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + description: | + Define custom rate limiting settings for a consumer group. This endpoint overrides the settings of the Rate Limiting Advanced plugin. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + '401': + $ref: '#/components/responses/HTTP401Error' + requestBody: + content: + application/json: + schema: + type: object + properties: + config.limit: + type: string + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + config.window_size: + type: string + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + example: ' 10' + config.window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + default: sliding + enum: + - sliding + - fixed + config.retry_after_jitter_max: + type: string + description: The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + required: + - config.limit + - config.window_size + examples: + Request body: + value: + config.limit: string + config.window_size: ' 10' + config.window_type: sliding + config.retry_after_jitter_max: string + description: | + Request Body + tags: + - consumer_groups + delete: + summary: Delete the configurations for a consumer group + operationId: delete-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete custom rate limiting settings for a consumer group. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + tags: + - consumer_groups + '/consumer_groups/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer group. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a consumer group + tags: + - Plugins + operationId: list-plugins-consumer-group + post: + description: Create a new plugin associated with a Consumer Group + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a consumer group + tags: + - Plugins + operationId: create-plugin-for-consumer-group + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumer_groups/{consumer_group_name_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a a consumer group using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a consumer group + tags: + - Plugins + operationId: delete-plugin-for-consumer-group + get: + description: Get a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Not Found + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: Not found + properties: + message: + type: string + example: Not Found + description: 404 Not Found + examples: + Not Found: + value: + message: Not Found + summary: Fetch a plugin associated with a Consumer Group + tags: + - Plugins + operationId: fetch-plugin-with-consumer-group + patch: + description: Update a plugin associated with a consumer group using the consumergroup name or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a consumer group + tags: + - Plugins + operationId: update-plugin-with-consumer-group + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer Group + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-customer-group + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_group_name_or_id' + - $ref: '#/components/parameters/plugin_id' + '/{workspace}/consumer_groups': + parameters: + - $ref: '#/components/parameters/workspace' + get: + summary: List consumer groups + tags: + - consumer_groups + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups_with_workspace + description: | + List all consumer groups + + Use consumer groups to manage consumer affiliation. + post: + summary: Create a consumer group + operationId: post-consumer_groups_with_workspace + responses: + '201': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a new consumer group. + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List a specific consumer group + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumer_groups-group_name_with_workspace + description: Returns a consumer group by passing either the `group_name` or `group_id` as a path parameter. + tags: + - consumer_groups + put: + summary: Create consumer group + operationId: put-consumer_groups-group_name_or_id_with_workspace + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: Create a consumer group by passing a new group name as the path parameter + requestBody: + $ref: '#/components/requestBodies/consumer_group_request' + tags: + - consumer_groups + delete: + summary: Delete a consumer group + operationId: delete-consumer_groups-group_name_or_id_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a consumer group. Deleting a consumer group removes all consumers from that group. This operation does not delete existing consuemrs. + tags: + - consumer_groups + '/{workspace}/consumers/{consumer_username_or_id}/consumer_groups': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/Gatewayapi_Consumer_username_or_id' + get: + summary: List consumer groups for a consumer + responses: + '200': + $ref: '#/components/responses/consumer_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-consumers-consumer_name_or_id-consumer_groups_with_workspace + description: | + View all consumer groups that a consumer is assigned to. + tags: + - consumer_groups + parameters: + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-size' + post: + summary: Add a consumer to a specific consumer group. + operationId: post-consumers-consumer_username_or_id-consumer_groups_with_workspace + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + requestBody: + content: + application/json: + schema: + type: object + properties: + group: + type: string + description: | + The name or ID of the group to add the consumer to. + example: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + required: + - group + examples: + Example request body: + value: + group: 288f2bfc-04e2-4ec3-b6f3-40408dff5417 + description: The request body contains the group ID for the group that you are adding a consumer into. + tags: + - consumer_groups + delete: + summary: Remove a consumer from all groups + operationId: delete-consumers-consumer_username_or_id-consumer_groups_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + description: Remove a consumer from all groups. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}/consumers': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + get: + summary: List all consumers in a consumer group + tags: + - consumer_groups + operationId: get-consumer_groups-group_name_or_id-consumers_with_workspace + description: List all consumers in a consumer group + parameters: + - $ref: '#/components/parameters/Gatewayapi_Pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/consumer_response' + '401': + $ref: '#/components/responses/HTTP401Error' + post: + summary: Add a consumer to a group + operationId: post-consumer_groups-group_name_or_id-consumers_with_workspace + responses: + '200': + $ref: '#/components/responses/add_consumer_to_group_response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Add a consumer to a specific consumer group. + + If you add a consumer to multiple groups: + + If all groups are allowed by the Rate Limiting Advanced plugin, only the first group's settings will apply. + Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active. + tags: + - consumer_groups + requestBody: + content: + application/json: + schema: + type: object + properties: + consumer: + type: string + description: | + The name or ID of the consumer to add to this group. + example: 8a4bba3c-7f82-45f0-8121-ed4d2847c4a4 + delete: + summary: Remove all consumers from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes all consumers from a specified consumer group. + tags: + - consumer_groups + '/{workspace}/consumers/{consumer_name_or_id}/consumer_groups/{group_name_or_id}': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_name_or_id' + - $ref: '#/components/parameters/group_name_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumers-consumer_name_or_id-consumer_groups-group_name_or_id_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Removes a consumer from a consumer group. This operation does not delete the consumer group. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}/consumers/{consumer_username_or_id}': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + - $ref: '#/components/parameters/consumer_username_or_id' + delete: + summary: Remove a consumer from a consumer group + operationId: delete-consumer_groups-group_name_or_id-consumers-consumer_name_or_id_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: The consumer groups endpoint for removing a consumer from a specified consumer group. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{group_name_or_id}/overrides/plugins/rate-limiting-advanced': + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/group_name_or_id' + put: + summary: Configure rate limiting for a consumer group. + operationId: put-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced_with_workspace + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + x-examples: + Example 1: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + properties: + config: + type: object + properties: + limit: + type: array + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + retry_after_jitter_max: + type: integer + description: | + The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + window_size: + type: array + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + items: + type: integer + example: 10 + window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + example: sliding + group: + type: string + description: The consumer group + example: test-group + plugin: + type: string + description: The name of the plugin + example: rate-limiting-advanced + examples: + 'Example ': + value: + config: + limit: + - 10 + retry_after_jitter_max: 0 + window_size: + - 10 + window_type: sliding + group: test-group + plugin: rate-limiting-advanced + description: | + Define custom rate limiting settings for a consumer group. This endpoint overrides the settings of the Rate Limiting Advanced plugin. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + '401': + $ref: '#/components/responses/HTTP401Error' + requestBody: + content: + application/json: + schema: + type: object + properties: + config.limit: + type: string + description: | + An array of one or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified. + config.window_size: + type: string + description: | + An array of one or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified. + example: ' 10' + config.window_type: + type: string + description: | + Set the time window type to either sliding (default) or fixed. + default: sliding + enum: + - sliding + - fixed + config.retry_after_jitter_max: + type: string + description: The upper bound of a jitter (random delay) in seconds to be added to the Retry-After header of denied requests (status = 429) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is 0; in this case, the Retry-After header is equal to the RateLimit-Reset header. + required: + - config.limit + - config.window_size + examples: + Request body: + value: + config.limit: string + config.window_size: ' 10' + config.window_type: sliding + config.retry_after_jitter_max: string + description: | + Request Body + tags: + - consumer_groups + delete: + summary: Delete the configurations for a consumer group + operationId: delete-consumer_groups-group_name_or_id-overrides-plugins-rate-limiting-advanced_with_workspace + responses: + '204': + description: | + HTTP/1.1 204 No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete custom rate limiting settings for a consumer group. As of Kong Gateway 3.4, you can scope plugins to consumer groups using only the `/consumer_groups` endpoint. Using `overrides` is deprecated, and no longer recommended. + tags: + - consumer_groups + '/{workspace}/consumer_groups/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer group. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all plugins associated with a consumer group + tags: + - Plugins + operationId: list-plugins-consumer-group_with_workspace + post: + description: Create a new plugin associated with a Consumer Group + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new plugin associated with a consumer group + tags: + - Plugins + operationId: create-plugin-for-consumer-group_with_workspace + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_username_or_id' + '/{workspace}/consumer_groups/{consumer_group_name_or_id}/plugins/{plugin_id}': + delete: + description: Delete a plugin associated with a a consumer group using ID. + responses: + '204': + description: Successfully deleted plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a consumer group + tags: + - Plugins + operationId: delete-plugin-for-consumer-group_with_workspace + get: + description: Get a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Not Found + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: Not found + properties: + message: + type: string + example: Not Found + description: 404 Not Found + examples: + Not Found: + value: + message: Not Found + summary: Fetch a plugin associated with a Consumer Group + tags: + - Plugins + operationId: fetch-plugin-with-consumer-group_with_workspace + patch: + description: Update a plugin associated with a consumer group using the consumergroup name or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a consumer group + tags: + - Plugins + operationId: update-plugin-with-consumer-group_with_workspace + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update a plugin associated with a Consumer Group using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a Consumer Group + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-customer-group_with_workspace + parameters: + - $ref: '#/components/parameters/workspace' + - $ref: '#/components/parameters/consumer_group_name_or_id' + - $ref: '#/components/parameters/plugin_id' + /licenses: + get: + summary: List licenses + tags: + - licenses + responses: + '200': + $ref: '#/components/responses/license-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-licenses + description: | + List active licenses. The data planes use the most recent updated_at license. + post: + summary: Add a license + operationId: post-licenses + responses: + '201': + $ref: '#/components/responses/license-response' + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Create a license using an auto-generated UUID. When using `POST`, if the request payload does contain a valid Kong Gateway license, the license will be added. + + If the request payload does not contain a valid licence, a `400 BAD REQUEST` will be returned. + requestBody: + $ref: '#/components/requestBodies/license-request' + tags: + - licenses + '/licenses/{license-id}': + parameters: + - $ref: '#/components/parameters/license-id' + get: + summary: List a specific license + responses: + '200': + $ref: '#/components/responses/license-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-licenses-license-id + description: List a specific license using the license id parameter. + tags: + - licenses + put: + summary: Update or add a license + operationId: put-licenses-license-id + responses: + '200': + $ref: '#/components/responses/license-response' + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + '405': + description: Method Not Allowed + description: |- + When using `PUT`, if the request payload does not contain an entity's primary key (`id` for licenses), the license will be added and assigned the given ID. + + If the request payload does contain an entity's primary key (id for Licenses), the license will be replaced with the given payload attribute. If the ID is not a valid UUID, a `400 BAD REQUEST` will be returned. If the ID is omitted, a `405 NOT ALLOWED` will be returned. + requestBody: + $ref: '#/components/requestBodies/license-request' + tags: + - licenses + patch: + summary: Update a license + operationId: patch-licenses-license-id + responses: + '200': + $ref: '#/components/responses/license-response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + When using `PATCH`, if the request payload does contain an entity's primary key (`id` for licenses), the license will be replaced with the given payload attribute. + + If the request payload does not contain an entity's primary key (`id` for licenses), a `404 NOT FOUND `will be returned or if the request payload contains a invalid licence, a `400 BAD REQUEST` will be returned. + requestBody: + $ref: '#/components/requestBodies/license-request' + tags: + - licenses + delete: + summary: Delete a license + operationId: delete-licenses-license-id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete a license by passing the license ID as a path parameter. + tags: + - licenses + /license/report: + get: + summary: Generate a report + tags: + - licenses + responses: + '200': + $ref: '#/components/responses/report-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-license-report + description: | + Generate a report on the Kong Gateway instance to gather monthly usage data. + /keyring: + get: + summary: Fetch cluster Keyring + tags: + - Keyring + responses: + '200': + $ref: '#/components/responses/key-ring-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-keyring + description: Kong Gateway provides a mechanism to store sensitive data fields, such as consumer secrets, in an encrypted format within the database.This provides for encryption-at-rest security controls in a Kong cluster. For more information review the [keyring and data encryption documentation](https://docs.konghq.com/gateway/latest/kong-enterprise/db-encryption/#getting-started). + /endpoints: + get: + summary: List all endpoints + tags: + - Information + responses: + '200': + $ref: '#/components/responses/get-endpoints' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-endpoints + description: List all available endpoints provided by the Admin API. + '/{endpoint}': + parameters: + - schema: + type: string + example: key + name: endpoint + in: path + required: true + description: Any available endpoint + head: + summary: Check endpoint or entity existence + operationId: head-endpoints + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:38:29 GMT' + Content-Type: + description: The media type of the message content + schema: + type: string + example: text/html; charset=UTF-8 + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: aqETeVmkeiGnAMzdUT2JRWroB2myY1lB + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '404': + description: Endpoint does not exist + headers: {} + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Similar to `HTTP` GET, but does not return the body. Returns HTTP 200 when the endpoint exits or HTTP 404 when it does not. Other status codes are possible. + tags: + - Information + options: + summary: List method by endpoint + operationId: options-endpoint + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:24:17 GMT' + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + Access-Control-Allow-Headers: + description: Used in response to a preflight request to indicate which HTTP headers can be used during the actual request + schema: + type: string + example: 'Content-Type, Kong-Admin-Token, Kong-Request-Type, Cache-Control' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: gDP1cF3OsNbrgcKPhRNE0RXRNfS7NcoG + Allow: + description: Lists the HTTP methods that are supported for the resource + schema: + type: string + example: 'OPTIONS, PATCH, POST' + Access-Control-Allow-Methods: + description: Indicates the methods allowed when accessing the resource in response to a preflight request + schema: + type: string + example: 'OPTIONS, PATCH, POST' + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request. + tags: + - Information + '/schemas/{entity}/validate': + parameters: + - schema: + type: string + name: entity + in: path + required: true + get: + summary: Retrieve entity schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + - id: + auto: true + type: string + uuid: true + properties: + fields: + type: array + description: A value of a schema + items: + type: object + properties: + id: + type: object + description: A value of a schema + properties: + auto: + type: boolean + description: A value of a schema + type: + type: string + description: A value of a schema + uuid: + type: boolean + description: A value of a schema + examples: + A mock schema: + value: + fields: + - id: + auto: true + type: string + uuid: true + - created_at: + auto: true + timestamp: true + type: integer + operationId: get-schemas-entity + description: Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations with Kong. + post: + summary: Validate a configuration against a schema + operationId: post-schemas-entity-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + Message: + type: string + example: schema validation successful + description: A success message + examples: + schema validation successful: + value: + Message: schema validation successful + description: |- + Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Information + + '/schemas/plugins/{plugin_name}': + parameters: + - schema: + type: string + example: basic-auth + name: plugin_name + in: path + required: true + description: The name of a Kong plugin + get: + summary: Retrieve Plugin Schema + tags: + - Information + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-plugins-plugin_name + description: | + Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system. + /schemas/plugins/validate: + post: + summary: Validate plugin schema + operationId: post-schemas-plugins-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: schema validation successful + properties: + message: + type: string + description: A successful message + example: schema validation successful + examples: + schema validation successful: + value: + message: schema validation successful + description: |- + Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + + This only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Information + /timers: + get: + summary: Retrieve Runtime Debugging Info of Kong's Timers + tags: + - Information + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + stats: + sys: + total: 13 + waiting: 12 + runs: 6771 + pending: 0 + running: 1 + flamegraph: + pending: '' + running: '' + elapsed_time: '' + timers: + router-rebuild: + is_running: false + name: router-rebuild + stats: + runs: 464 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 464 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off': + is_running: false + name: 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off' + stats: + runs: 3 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 3 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + worker: + id: 0 + count: 5 + properties: + stats: + type: object + description: Statistics about the worker + properties: + sys: + type: object + description: List of the number of different type of timers + properties: + total: + description: The total number of timers (running + pending + waiting) + type: integer + default: 7 + example: 7 + waiting: + description: The number of unexpired timers + type: integer + default: 7 + example: 7 + runs: + description: The total number of runs for the timers + type: integer + default: 7 + example: 7 + pending: + description: The number of pending timers + type: integer + default: 0 + example: 0 + running: + description: The number of running timers + type: integer + default: 0 + example: 0 + flamegraph: + type: object + description: String-encoded timer-related flamegraph data + properties: + pending: + description: The number of pending timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + running: + description: The number of running timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + elapsed_time: + description: The elapsed time for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17 + timers: + description: Timer statistics for the worker + type: object + properties: + meta: + description: Program callstack of created timers + type: object + properties: + name: + description: The name of the timer's metadata + type: string + example: '@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()' + worker: + type: object + properties: + id: + type: integer + description: The ordinal number of the current Nginx worker processes (starting from number 0). + count: + type: integer + description: The total number of the Nginx worker processes. + operationId: get-timers + description: Retrieve runtime stats data from [lua-resty-timer-ng](https://github.com/Kong/lua-resty-timer-ng). + + /status: + get: + summary: Health Routes + tags: + - Information + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_workspaces: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_keyring: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + properties: + memory: + type: object + description: Metrics about the memory usage. + properties: + lua_shared_dicts: + type: object + description: An array of dictionary objects that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (`capacity`) and how much of said memory is in use (`allocated_slabs`). + properties: + kong_core_db_cache: + type: object + properties: + capacity: + type: string + example: 128.00 MiB + description: Memory capacity + allocated_slabs: + type: string + example: 128.00 MiB + description: Total allocated memory + workers_lua_vms: + type: array + description: An array with all workers of the Kong node, each entry contains a `http_allocated_gc` string and a `pid`. + items: + type: object + properties: + http_allocated_gc: + type: string + description: | + HTTP submodule's Lua virtual machine's memory usage information. + pid: + type: integer + description: A worker's process identification number. + example: 18478 + database: + type: object + description: Metrics about the database + properties: + reachable: + type: boolean + description: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself. + server: + type: object + description: Metrics about the nginx HTTP/S server + properties: + connections_reading: + type: integer + description: The current number of connections where Kong is reading the request header. + example: 3 + connections_writing: + type: integer + description: The current number of connections where nginx is writing the response back to the client. + example: 1 + total_requests: + type: integer + description: The total number of client requests. + example: 1 + connections_waiting: + type: integer + description: The current number of idle client connections waiting for a request. + example: 1 + connections_handled: + type: integer + description: The total number of handled connections. Generally, the parameter value is the same as the `connections_accepted` parameter unless some resource limits have been reached. + example: 1 + connections_active: + type: integer + description: The current number of active client connections including waiting connections. + example: 1 + connections_accepted: + type: integer + description: The total number of accepted client connections. + example: 1 + examples: + Status endpoint response: + value: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_workspaces: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_keyring: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + operationId: get-status + description: |- + Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, the status of the database connection, and node's memory usage. + + `status_listen` listens on port `8007` by default, however `8001` can be used for status checks as well. The status endpoint provides detailed metrics regarding memory usage, worker process stats, database connection status, and server connection metrics. + + If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used. + + /status/dns: + get: + summary: DNS Status + tags: + - Information + operationId: getDnsStatus + description: | + Retrieve DNS worker and stats information. If the legacy DNS client is in use, it returns a 501 status with a message. + responses: + '200': + description: DNS worker and stats information + content: + application/json: + schema: + type: object + properties: + worker: + type: object + description: Worker information. + properties: + id: + type: integer + description: The worker ID. + example: 1 + count: + type: integer + description: The total number of workers. + example: 4 + stats: + type: object + description: DNS stats information (specific details depend on the Kong instance). + '501': + description: Legacy DNS client in use + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Message indicating that the endpoint is not implemented with the legacy DNS client. + example: "not implemented with the legacy DNS client" + '401': + $ref: '#/components/responses/HTTP401Error' + /keyring/generate: + post: + summary: Generate key + operationId: post-keyring-generate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + properties: + key: + type: string + description: Key material + example: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: + type: string + description: The key's ID + example: 8zgITLQh + description: |- + Generate key material. + + Kong supports rotating keys by allowing for multiple keys to exist on the keyring at the same time. This allows for data fields written by one key to be read back, while a fresher encryption key is used for write operations. Rotating keys is a matter of importing or generating a new key into the keyring, and marking it as active. + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Keyring + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + properties: + key: + type: string + example: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: + type: string + example: 8zgITLQh + examples: + Example 1: + value: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + /keyring/activate: + post: + summary: Activate key + operationId: post-keyring-activate + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Kong can write new sensitive data fields with the current active key, and read previously written fields in the database with the prior key, provided that key is in the keyring. Kong automatically selects the appropriate key to use when decrypting fields from the database. + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: 3Rwvk223 + properties: + key: + type: string + description: The key ID + example: 3Rwvk223 + description: The request body contains a key ID that can be generated from the `/keyring/generate` endpoint. + tags: + - Keyring + /keyring/recover: + post: + summary: Recover keyring + operationId: post-keyring-recover + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: successfully recovered 1 keys + recovered: + - RfsDJ2Ol + not_recovered: + - xSD219lH + properties: + message: + type: string + description: A message containing details about your request. + example: successfully recovered 1 keys + recovered: + type: array + items: + type: string + example: RfsDJ2Ol + not_recovered: + type: array + items: + type: string + example: xSD219lH + examples: + example: + value: + message: successfully recovered 1 keys + recovered: + - RfsDJ2Ol + not_recovered: + - xSD219lH + description: | + The keyring material is then encrypted with the public RSA key defined with the `keyring_recovery_public_key` Kong configuration value in the database. The corresponding private key can be used to decrypt the keyring material in the database. + + The response contains a list of keys that were successfully recovered and that could not be recovered. The Kong error log will contain the detailed reason why the keys could not be recovered. + requestBody: + description: |- + The request body contains a single file named `recovery_private_key` that represents a private RSA key used for decrypting a keyring material stored in the database. + + The private key is uploaded in the PEM format, which is a binary format used for storing cryptographic keys and certificates. The contents of the file are encoded as a string using a specified encoding (such as base64) and included in the request body + content: + multipart/form-data: + schema: + type: object + properties: + recovery_private_key: + type: string + format: binary + example: /path/to/generated/ + description: Private key in PEM format. + examples: + Example 1: + value: + recovery_private_key: /path/to/generated/ + tags: + - Keyring + /keyring/remove: + post: + summary: Remove key + operationId: post-keyring-remove + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Remove a key from the keyring. + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: 3Rwvk223 + properties: + key: + type: string + description: The key ID + example: 3Rwvk223 + description: The request body contains a key ID that can be generated from the `/keyring/generate` endpoint. + tags: + - Keyring + /keyring/export: + post: + summary: Export keyring + operationId: post-keyring-export + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: eyJrIjoIn0= + description: opaque blob containing a keyring. + properties: + data: + type: string + example: eyJrIjoiV1JZeTdubDlYeFZpR3VVQWtWTXBcL0JiVW1jMWZrWHluc0dKd + examples: + Example: + value: + data: eyJrIjoiV1JZeTdubDlYeFZpR3VVQWtWTXBcL0JiVW1jMWZrWHluc0dKd + description: | + Export the keyring. The exported material can be re-imported to the cluster in the event of an outage or to restore a previously-deleted key. + The exported keyring should be stored in a safe location for disaster recovery purposes. It is not designed to be modified or decrypted before being used during a disaster recovery process. + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Keyring + /tags: + get: + summary: List all tags + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags + description: |- + Returns a paginated list of all the tags in the system. + + The list of entities isn't restricted to a single entity type. All the entities tagged with tags are present in this list. + + If an entity is tagged with more than one tag, the `entity_id` for that entity appears more than once in the resulting list. Similarly, if several entities have been tagged with the same tag, the tag appears in several items of this list. + '/tags/{tags}': + parameters: + - $ref: '#/components/parameters/tag' + get: + summary: List entity by tag + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags-tags + description: |- + Returns the entities that have been tagged with the specified tag. + + The list of entities isn't restricted to a single entity type. All the entities tagged with tags are present in this list. + /keyring/import: + post: + summary: Import Keyring + operationId: post-keyring-import + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + created_at: 1576518704 + consumer: + id: 6375b5fd-9c95-4822-b2dd-80ffbccb7ec9 + id: fc46ce48-c1d6-4078-9f51-5a777350a8a2 + password: da61c0083b6d19ef3db2490d0da96a71572da0fa + username: bob + properties: + created_at: + type: integer + description: Datetime representation of the keyring creation date. + consumer: + type: object + description: The consumer object. + properties: + id: + type: string + example: 6375b5fd-9c95-4822-b2dd-80ffbccb7ec9 + description: ID of the consumer object. + id: + type: string + example: 6375b5fd-9c95-4822-b2dd-80ffbccb7ec9 + description: UUID of the keyring + password: + type: string + example: da61c0083b6d19ef3db2490d0da96a71572da0fa + description: Password associated with the keyring. + username: + type: string + example: user + description: Username associated with the keyring + description: Restart Kong and re-import the previously exported keyring. This operation requires that the keyring_private_key point to the private RSA key associated with the public key used during the initial keyring export. + tags: + - Keyring + requestBody: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + key: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: 8zgITLQh + properties: + key: + type: string + example: t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44= + id: + type: string + example: 8zgITLQh + examples: + Example 1: + value: {} + description: Import Keyring + '/schemas/vaults/{vault_name}': + parameters: + - schema: + type: string + name: vault_name + in: path + required: true + description: The vault schema to be returned + get: + summary: Retrieve Vault Schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: No vault named + operationId: get-schemas-vaults-vault_name + description: Retrieve the schema of a vault. + post: + summary: Validate Vault Schema + tags: + - Validation + requestBody: + description: Payload containing the schema data to validate + required: true + content: + application/json: + schema: + type: object + properties: + schemaData: + type: string + description: JSON string containing the vault schema data + responses: + '200': + description: Validation successful + content: + application/json: + schema: + type: object + properties: + validation: + type: boolean + description: Indicates if the schema is valid + '400': + description: Bad request due to invalid schema data + '405': + description: Method Not Allowed + operationId: post-schemas-vaults-validate + description: Validates the given vault schema data against predefined validation rules. + /admins: + get: + summary: List Admins + tags: + - admins + responses: + '200': + $ref: '#/components/responses/admins-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-admins + description: Returns a list of admins. To query all admins, add a parameter `all_workspaces=true` to the `/admins` endpoint. The `status` field in the response indicates the state of the admins invitation. `0`= Approved, `1`= Pending, `2`= Rejected, `3`= Revoked, `4` = Invited, `5`= Unverified. + post: + summary: Invite an Admin + operationId: post-admins + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + admin: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + status: + type: integer + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + x-examples: + Example 1: + admin: + created_at: 1556638641 + id: 8f0a742f-07f3-49e0-90d7-4fc7eea7e6a4 + updated_at: 1556638641 + status: 4 + username: test-case-3 + email: test3@test.com + rbac_token_enabled: true + examples: + Example admin response: + value: + admin: + created_at: 0 + id: string + updated_at: 0 + status: 0 + username: string + email: string + rbac_token_enabled: true + '409': + description: Conflict + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Detail about the conflict + example: user already exists with same username, email, or custom_id + x-exmples: + Example 1: + message: user already exists with same username, email, or custom_id + examples: + Constraint violation: + value: + message: user already exists with same username, email, or custom_id + tags: + - admins + description: Invite an admin to your organization. + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + example: email@example.com + description: The admin's email address. + username: + type: string + description: The admin's username + example: myusername + custom_id: + type: string + description: The admin's custom ID + rbac_token_enabled: + type: boolean + description: Allows the admin to use and reset their RBAC token. + default: true + examples: + Invite an admin: + value: + username: test-case-3 + email: test3@test.com + custom_id: customId + rbac_token_enabled: true + /admins/register: + post: + summary: Register an Admin’s Credentials + operationId: post-admins-register + responses: + '201': + description: Created + '401': + $ref: '#/components/responses/HTTP401Error' + description: Register an Admin's Credentials + requestBody: + content: + application/json: + schema: + type: object + properties: + token: + type: string + + username: + type: string + + email: + type: string + + format: email + password: + type: string + + format: password + examples: + Example registration request: + value: + token: string + username: string + email: user@example.com + password: pa$$word + tags: + - admins + /admins/password_resets: + post: + summary: Send a Password Reset Email to an Admin + tags: + - admins + responses: + '201': + description: Created + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-admins-password_resets + description: Using a registered admin's email address issue a password reset email to the admin. + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + + description: The registered admin's email. + example: admin@example.com + examples: + Example reset body: + value: + email: admin@example.com + patch: + summary: Reset an Admin’s Password + operationId: patch-admins-password_resets + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + description: Reset an admin's password. + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + + password: + type: string + + token: + type: string + + examples: + Example 1: + value: + email: string + password: string + token: string + tags: + - admins + '/admins/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The admin’s username or ID. + get: + summary: Retrieve an Admin + tags: + - admins + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + status: + type: integer + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + x-examples: + Example 1: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + status: 4 + username: test-admin + email: test@test.com + rbac_token_enabled: true + examples: + Example response body: + value: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + status: 4 + username: test-admin + email: test@test.com + rbac_token_enabled: true + operationId: get-admins-name_or_id + description: Retrieve an admin using their name or ID. Using `generate_register_url`, you can generate a unique registration URL if the admin's invitation status is `4`. `generate_register_url` overrides the previous registration URL for the particular admin each time it is requested. + patch: + tags: + - admins + summary: Update an Admin + operationId: patch-admins-name_or_id-generate_register_url + responses: + '200': + description: OK + requestBody: + content: + application/json: + schema: + type: object + properties: + name_or_id: + type: string + username: + type: string + email: + type: string + rbac_token_enabled: + type: boolean + x-examples: + Example 1: + name_or_id: 665b4070-541f-48bf-82c1-53030babaa81 + username: test-renamed + email: test@test.com + rbac_token_enabled: true + examples: + Example 1: + value: + name_or_id: string + username: string + email: string + rbac_token_enabled: true + description: Update information about an admin + delete: + tags: + - admins + summary: Delete an Admin + operationId: delete-admins-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete an admin by specifying the admin's username or ID. + '/admins/{name_or_id}/roles': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The admin’s username or ID + get: + summary: List an Admin’s Roles + tags: + - admins + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + is_default: + type: boolean + x-examples: + Example 1: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + examples: + Example role list: + value: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + operationId: get-admins-name_or_id-roles + description: List all roles related to a registered admin. + post: + summary: Create or Update an Admin’s Roles + operationId: post-admins-name_or_id-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + is_default: + type: boolean + x-examples: + Example 1: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + name: super-admin + is_default: false + examples: + Example role assignment: + value: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1556563122 + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + is_default: false + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + name: super-admin + is_default: false + tags: + - admins + requestBody: + content: + application/json: + schema: + type: object + properties: + roles: + type: string + x-examples: + Example 1: + roles: read-only + description: Comma-separated string of role names to create or update for an admin. + description: Create or update roles for an admin + delete: + tags: + - admins + summary: Delete an Admin’s Role + operationId: delete-admins-name_or_id-roles + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete an admin's roles by passing a comma-separated string of names of specific roles to remove from an admin. + '/admins/{name_or_id}/workspaces': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The admin’s username or ID + get: + summary: List an Admin’s Workspaces + tags: + - admins + responses: + '200': + $ref: '#/components/responses/workspace-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-admins-name_or_id-workspaces + description: Return workspaces associated with an admin. + /groups: + get: + summary: List Groups + tags: + - groups + responses: + '200': + $ref: '#/components/responses/groups-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-groups + description: Returns a list of groups. + post: + summary: Create a new group + operationId: post-groups + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + name: + type: string + comment: + type: string + x-examples: + Example 1: + created_at: 1556638641 + id: 8f0a742f-07f3-49e0-90d7-4fc7eea7e897 + updated_at: 1556638641 + name: demo-group + comment: comment + examples: + Example group response: + value: + created_at: 0 + id: string + updated_at: 0 + name: string + comment: string + tags: + - groups + description: Create a group to your organization. + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The group's name + example: my_group + examples: + Create a group: + value: + name: demo-group + comment: comment + '/groups/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The group’s name or ID. + get: + summary: Retrieve a Group + tags: + - groups + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + updated_at: + type: integer + name: + type: string + comment: + type: string + x-examples: + Example 1: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + name: test-group + comment: comment1 + examples: + Example response body: + value: + created_at: 1556638385 + id: 665b4070-541f-48bf-82c1-53030babaa81 + updated_at: 1556638385 + username: test-group + comment: comment + operationId: get-groups-name_or_id + description: Retrieve a group using their name or ID. + patch: + tags: + - groups + summary: Update a Group + operationId: patch-groups-name_or_id + responses: + '200': + description: OK + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + comment: + type: string + x-examples: + Example 1: + name: test-group + comment: comment1 + examples: + Example 1: + value: + name: string + comment: string + description: Update information about a group + delete: + tags: + - groups + summary: Delete an Group + operationId: delete-groups-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete a group by specifying the group's name or ID. + '/groups/{name_or_id}/roles': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The group’s username or ID + get: + summary: List an Group’s Roles + tags: + - groups + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + group: + type: object + properties: + id: + type: string + name: + type: string + comment: + type: string + updated_at: + type: string + format: date-time + rbac_role: + type: object + properties: + id: + type: string + name: + type: string + workspace: + type: object + properties: + id: + type: string + next: + nullable: true + x-examples: + Example 1: + data: + - group: + comment: 'comment1' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: demo-group + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + examples: + Example role list: + value: + data: + - group: + comment: 'comment1' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: demo-group + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + operationId: get-groups-name_or_id-roles + description: List all roles related to a group. + post: + summary: Create or Update a Group's Roles + operationId: post-groups-name_or_id-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + group: + type: object + properties: + id: + type: string + name: + type: string + comment: + type: string + updated_at: + type: string + format: date-time + rbac_role: + type: object + properties: + id: + type: string + name: + type: string + workspace: + type: object + properties: + id: + type: string + x-examples: + Example 1: + group: + comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + examples: + Example role assignment: + value: + group: + comment: 'Read access to all endpoints, across all workspaces' + created_at: 1556563122 + id: 7574eb1d-c9fa-46a9-bd3a-3f1b4b196287 + name: read-only + is_default: false + rbac_role: + id: 7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d + name: admin + workspace: + id: 99bd8d18-f5b6-410e-aefe-d75f4252f13c + tags: + - groups + requestBody: + content: + application/json: + schema: + type: object + properties: + rbac_role_id: + type: string + workspace_id: + type: string + x-examples: + Example 1: + rbac_role_id: 12773c9a-7f7c-45f2-bcea-5285eb18fd2f + workspace_id: d107bce7-dd86-4124-93c8-667ecc34b32e + description: Comma-separated string of role names to create or update for a group. + description: Create or update roles for a admin + delete: + tags: + - groups + summary: Delete a group’s Role + operationId: delete-groups-name_or_id-roles + parameters: + - name: rbac_role_id + in: query + required: true + schema: + type: string + example: 12773c9a-7f7c-45f2-bcea-5285eb18fd2f + - name: workspace_id + in: query + required: true + schema: + type: string + example: d107bce7-dd86-4124-93c8-667ecc34b32e + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: Delete a group's roles. + '/debug/cluster/control-planes-nodes/log-level/{log_level}': + parameters: + - schema: + type: string + enum: + - debug + - info + - notice + - warn + - error + - crit + name: log_level + in: path + required: true + description: The log level + put: + summary: Set Node Log Level of All Control Plane Nodes + operationId: put-debug-cluster-control-planes-nodes-log-level-log_level + responses: + '200': + description: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Change the log level of all control plane nodes deployed in a hybrid (CP/DP) cluster. + Be careful when changing the log level of a node to debug in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level, such as notice. + It’s currently not possible to change the log level of data plane and DB-less nodes. + + This endpoint can be protected with RBAC, and changes will be reflected in the audit logs. + The log level change is propagated to all Nginx workers of a node, including to newly spawned workers. + + Log levels are set in Kong’s configuration. Possible log levels in increasing order of severity: `debug`, `info`, `notice`, `warn`, `error`, and `crit`. For more information, review the [logging reference](https://docs.konghq.com/gateway/latest/production/logging/). + + When a user dynamically changes the log level for the entire cluster, if a new node joins the cluster, the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. To work around that, make sure the new node starts with the proper level by setting the startup `kong.conf` setting [`KONG_LOG_LEVEL`](https://docs.konghq.com/gateway/latest/reference/configuration/#log_level). + tags: + - debug + '/debug/cluster/log-level/{log_level}': + parameters: + - schema: + type: string + enum: + - debug + - info + - notice + - warn + - error + - crit + name: log_level + in: path + required: true + description: The log level + put: + summary: Set Node Log Level of All Nodes + operationId: put-debug-cluster-log-level-log_level + responses: + '200': + description: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - debug + description: |- + Change the log level of all nodes in a cluster. + + Be careful when changing the log level of a node to debug in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level, such as notice. + It’s currently not possible to change the log level of data plane and DB-less nodes. + + This endpoint can be protected with RBAC, and changes will be reflected in the audit logs. + The log level change is propagated to all Nginx workers of a node, including to newly spawned workers. + + Log levels are set in Kong’s configuration. Possible log levels in increasing order of severity: `debug`, `info`, `notice`, `warn`, `error`, and `crit`. For more information, review the [logging reference](https://docs.konghq.com/gateway/latest/production/logging/). + + Currently, when a user dynamically changes the log level for the entire cluster, if a new node joins the cluster, the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. To work around that, make sure the new node starts with the proper level by setting the startup `kong.conf` setting [`KONG_LOG_LEVEL`](https://docs.konghq.com/gateway/latest/reference/configuration/#log_level). + /debug/node/log-level: + get: + summary: Retrieve Node Log Level of A Node + tags: + - debug + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + message: + type: string + x-examples: + Example 1: + message: 'log level: debug' + examples: + Retrieved debug level: + value: + message: string + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-debug-node-log-level + description: | + Retrieve the current log level of a node. + + See the [Nginx Documentation](https://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + '/debug/node/log-level/{log_level}': + parameters: + - schema: + type: string + enum: + - debug + - info + - notice + - warn + - error + - crit + name: log_level + in: path + required: true + description: The log level + put: + summary: Set Log Level of A Single Node + tags: + - debug + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + message: + type: string + x-examples: + Example 1: + message: log level changed + examples: + Example 1: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-debug-node-log-level-log_level + description: | + Change the log level of a node. + /rbac/users: + get: + summary: List Users + tags: + - RBAC + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-users + description: |- + List all users. + + Note: RBAC users associated with admin aren't listed with `GET /rbac/users`. Instead, use `GET /admins` to list all admins. + post: + summary: Add a User + operationId: post-rbac-users + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + requestBody: + $ref: '#/components/requestBodies/rbac-request' + description: Add a User + '/rbac/users/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC username or UUID. + get: + summary: Retrieve a User + tags: + - RBAC + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-users-name_or_id + description: Retrieve a user by passing a name or ID in the path. + patch: + summary: Update a User + operationId: patch-rbac-users-name_or_id + responses: + '200': + $ref: '#/components/responses/rbac-user-response' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + description: Update a user. Users are unable to update their own roles. + requestBody: + $ref: '#/components/requestBodies/rbac-request' + delete: + summary: Delete a User + operationId: delete-rbac-users-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a user. + tags: + - RBAC + /rbac/roles: + get: + summary: List Roles + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + next: + type: string + x-examples: + Example 1: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + examples: + Multiple roles: + value: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + operationId: get-rbac-roles + description: List all roles. + post: + summary: Add a Role + operationId: post-rbac-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + New role response body: + value: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + + description: The RBAC role name. + comment: + type: string + + description: A string describing the RBAC user object. + description: The request body contains the name of the role and an optional attribute. + description: Add a role. + '/rbac/roles/{name_or_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: Retrieve a Role + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + Example 1: + value: + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id + description: Retrieve a role by passing the name or UUID as a path parameter. + put: + summary: Update or Create a Role + operationId: put-rbac-roles-name_or_id + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: the best + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: doc_lord + examples: + Example entity replacement: + value: + comment: the best + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: doc_lord + '201': + description: Created + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + comment: + type: string + + description: | + With a `PUT` request, if the request payload contains an existing entity’s primary key, the payload replaces the entity specified by the given primary key. If the primary key is not that of an existing entity, the entity is created with the given payload. + patch: + summary: Update a Role + operationId: patch-rbac-roles-name_or_id + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: comment from patch request + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + Patch request response: + value: + comment: comment from patch request + created_at: 1557532566 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + attribute: + type: string + + description: | + A string describing the RBAC role object. + description: Attribute request body + description: Updates a role by passing an optional attribute. + delete: + summary: Delete a Role + operationId: delete-rbac-roles-name_or_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + description: Delete a role + '/rbac/roles/{name_or_id}/endpoints': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: List Role Endpoints Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + data: + - actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + - actions: + - read + created_at: 1557764438 + endpoint: /services + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-endpoints + description: Lists all of a role's associated endpoint permissions. + post: + summary: Add a Role Endpoint Permission + operationId: post-rbac-roles-name_or_id-endpoints + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + examples: + Basic example: + value: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + tags: + - RBAC + description: |- + Add a role endpoint permission for the path of the associated endpoint. Permissions can be exact matches, or contain wildcards, represented by `*`. + + Exact matches: + - `/services/` + - `/services/foo` + + Wildcards: + - `/services/*` + - `/services/*/plugins` + Where `*` replaces exactly one segment between slashes (or the end of the path). + + Note that wildcards can be nested. For example, `/rbac/*`, `/rbac/*/*`, `/rbac/*/*/*` would refer to all paths under `/rbac/`. +

+ For the `admin` role in the default workspace, CRUD actions on `/groups` and `/groups/*` endpoints are disallowed. + For the `workspace-admin` role in non-default workspaces, CRUD actions on `/groups` and `/groups/*` endpoints are disallowed. + requestBody: + content: + application/json: + schema: + type: object + properties: + workspace: + type: string + + description: Workspace tied to the endpoint. Defaults to the default permission. Using the wildcard `*` means all workspaces are affected. + endpoint: + type: string + + description: | + Endpoint associated with this permission. + negative: + type: string + + description: | + If true, explicitly disallow the actions associated with the permissions tied to this endpoint. By default, this value is false. + actions: + type: string + + description: | + One or more actions associated with this permission, written as a comma-separated string. + For example, `read,create,update,delete`. + comment: + type: string + + description: A string describing the RBAC permission object. + '/rbac/roles/{name_or_id}/endpoints/{workspace_name_or_id}/{endpoint}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + - schema: + type: string + name: workspace_name_or_id + in: path + required: true + description: The workspace name or UUID. + - schema: + type: string + name: endpoint + in: path + required: true + description: The endpoint associated with this permission. + get: + summary: Retrieve a Role Endpoint Permission + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + examples: + basic example: + value: + actions: + - delete + - create + - update + - read + created_at: 1557764505 + endpoint: /consumers + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-endpoints-workspace_name_or_id-endpoint + description: | + Retrieve a Role Endpoint Permission + patch: + summary: Update a Role Endpoint Permission + operationId: patch-rbac-roles-name_or_id-endpoints-workspace_name_or_id-endpoint + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - update + - read + created_at: 1557764438 + endpoint: /services + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + examples: + Example 1: + value: + actions: + - delete + - create + - update + - read + created_at: 1557764438 + endpoint: /services + negative: false + role: + id: 23df9f20-e7cc-4da4-bc89-d3a08f976e50 + workspace: default + tags: + - RBAC + description: | + Update a Role Endpoint Permission + requestBody: + content: + application/json: + schema: + type: object + properties: + negative: + type: string + + description: | + If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. + actions: + type: string + + description: | + One or more actions associated with this permission. + delete: + summary: Delete a Role Endpoint Permission + operationId: delete-rbac-roles-name_or_id-endpoints-workspace_name_or_id-endpoint + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete a Role Endpoint Permission + tags: + - RBAC + '/rbac/roles/{name_or_id}/entities': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: List Entity Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + x-examples: + Example 1: + data: + - actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + Example 1: + value: + data: + - actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-entities + description: | + Add a Role Entity Permission + post: + summary: Add a Role Entity Permission + operationId: post-rbac-roles-name_or_id-entities + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + x-examples: + Example 1: + actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + example response: + value: + actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + tags: + - RBAC + description: The `entity_id` must be the ID of an entity in Kong. If you provide the ID of a workspace, the permission applies to all entities in that workspace. Future entities belonging to that workspace will get the same permissions. A wildcard (`*`) will be interpreted as all entities in the system. + requestBody: + content: + application/json: + schema: + type: object + description: If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. + properties: + negative: + type: string + + description: ID of the entity associated with this permission. + entity_id: + type: string + + description: Type of the entity of a given `entity_id`. + entity_type: + type: string + + description: One or more actions associated with this permission. + actions: + type: string + + description: | + One or more actions associated with this permission. + comment: + type: string + + description: A string describing the RBAC permission object. + description: | + Request Body + '/rbac/roles/{name_or_id}/entities/{entity_id}': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC permission name or UUID. + - schema: + type: string + name: entity_id + in: path + required: true + description: ID of the entity associated with this permission. + get: + summary: Retrieve a Role Entity Permission + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + x-examples: + Example 1: + actions: + - delete + - create + - read + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + example-response: + value: + actions: + - string + created_at: 0 + entity_id: string + entity_type: string + negative: true + role: + id: string + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-entities-entity_id + description: | + Retrieve a Role Entity Permission + patch: + summary: Update an Entity Permission + operationId: patch-rbac-roles-name_or_id-entities-entity_id + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + entity_id: + type: string + entity_type: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + x-examples: + Example 1: + actions: + - update + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + examples: + example-response: + value: + actions: + - update + created_at: 1557771505 + entity_id: '*' + entity_type: wildcard + negative: false + role: + id: bba049fa-bf7e-40ef-8e89-553dda292e99 + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - RBAC + description: Update an Entity Permission + requestBody: + content: + application/json: + schema: + type: object + properties: + negative: + type: boolean + + description: | + If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. + actions: + type: string + + description: One or more actions associated with this permission. + delete: + summary: Delete an Entity Permission + operationId: delete-rbac-roles-name_or_id-entities-entity_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete an Entity Permission + tags: + - RBAC + '/rbac/roles/{name_or_id}/permissions': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC role name or UUID. + get: + summary: List Role Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + endpoints: + type: object + properties: + '*': + type: object + properties: + '*': + type: object + properties: + actions: + type: array + items: + type: string + negative: + type: boolean + /*/rbac/*: + type: object + properties: + actions: + type: array + items: + type: string + negative: + type: boolean + entities: + type: object + properties: {} + x-examples: + Example 1: + endpoints: + '*': + '*': + actions: + - delete + - create + - update + - read + negative: false + /*/rbac/*: + actions: + - delete + - create + - update + - read + negative: true + entities: {} + examples: + role-permission-example: + value: + endpoints: + '*': + '*': + actions: + - delete + - create + - update + - read + negative: false + /*/rbac/*: + actions: + - delete + - create + - update + - read + negative: true + entities: {} + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-roles-name_or_id-permissions + description: List Role Permissions + '/rbac/users/{name_or_id}/roles': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC user name or UUID. + get: + summary: List a User’s Roles + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + user: + type: object + properties: + comment: + type: string + created_at: + type: integer + enabled: + type: boolean + id: + type: string + name: + type: string + user_token: + type: string + user_token_ident: + type: string + x-examples: + Example 1: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557765500 + id: a1c810ee-8366-4654-ba0c-963ffb9ccf2e + name: read-only + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + examples: + Example 1: + value: + roles: + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557765500 + id: a1c810ee-8366-4654-ba0c-963ffb9ccf2e + name: read-only + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + operationId: get-rbac-users-name_or_id-roles + description: | + Add a User to a Role + post: + summary: Add a User to a Role + operationId: post-rbac-users-name_or_id-roles + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + roles: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: string + name: + type: string + user: + type: object + properties: + comment: + type: string + created_at: + type: integer + enabled: + type: boolean + id: + type: string + name: + type: string + user_token: + type: string + user_token_ident: + type: string + x-examples: + Example 1: + roles: + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + examples: + example-role-created: + value: + roles: + - created_at: 1557772263 + id: aae80073-095f-4553-ba9a-bee5ed3b8b91 + name: doc-knight + user: + comment: null + created_at: 1557772232 + enabled: true + id: b65ca712-7ceb-4114-87f4-5c310492582c + name: gruce-wayne + user_token: $2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K + user_token_ident: 88ea3 + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Add a User to a Role + requestBody: + content: + application/json: + schema: + type: object + properties: + roles: + type: string + + description: Comma-separated list of role names to assign to the user. + tags: + - RBAC + delete: + summary: Delete a Role from a User + operationId: delete-rbac-users-name_or_id-roles + responses: + '204': + description: No Content + tags: + - RBAC + description: Delete a Role from a User + '/rbac/users/{name_or_id}/permissions': + parameters: + - schema: + type: string + name: name_or_id + in: path + required: true + description: The RBAC user name or UUID. + get: + summary: List a User’s Permissions + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + endpoints: + type: object + properties: + '*': + type: object + properties: + '*': + type: object + properties: + actions: + type: array + items: + type: string + negative: + type: boolean + entities: + type: object + properties: {} + x-examples: + Example 1: + endpoints: + '*': + '*': + actions: + - read + negative: false + entities: {} + examples: + Example 1: + value: + endpoints: + '*': + '*': + actions: + - read + negative: false + entities: {} + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-rbac-users-name_or_id-permissions + description: | + List a User’s Permissions + /filter-chains: + post: + summary: Add Filter Chain + operationId: post-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Create Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains + operationId: get-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + List All Filter Chains + '/routes/{route_id_or_name}/filter-chains': + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + post: + summary: Add Filter Chain + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_name_or_id-filter-chains + description: | + Create Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Route + operationId: get-routes-route_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + tags: + - filter-chains + description: | + List Filter Chains Associated to a Specific Route + patch: + summary: Update Filter Chain Associated to a Specific Route + operationId: patch-routes-route_id_or_name-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + '/services/{service_id_or_name}/filter-chains': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + post: + summary: Create Filter Chain Associated to a Specific Service + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-services-service_id_or_name-filter-chains + description: | + Add filter chain Associated to a Specific Service + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Service + operationId: get-service_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List Filter Chains Associated to a Specific Service + tags: + - filter-chains + '/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: Retrieve Filter Chain + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + operationId: get-filter-chains-filter_chain_id + description: | + Retrieve Filter Chain + '401': + $ref: '#/components/responses/HTTP401Error' + patch: + summary: Update Filter Chain + operationId: patch-filter-chains-filter_chain_id + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + put: + summary: Update Or Create Filter Chain + operationId: put-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: |- + Inserts (or replaces) the filter chain under the requested resource with the definition specified in the body. The filter chain is identified via the name or ID attribute. + + When the name or ID attribute has the structure of a UUID, the filter chain being inserted or replaced is identified by its ID. Otherwise, it is identified by its name. + + When creating a new filter chain without specifying an ID (neither in the URL nor in the body), the ID will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + delete: + summary: Delete Filter Chain + operationId: delete-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain. + tags: + - filter-chains + '/routes/{route_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: List Filter Chains Associated to a Specific Route + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter-chains-filter_chain_id + description: | + Retrieve filter chain associated to a specific route. + put: + summary: Create Or Update Filter Chain Associated to a Specific Route + operationId: put-routes-route_id_or_name-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Create or update filter chain associated to a specific route. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + tags: + - filter-chains + '/routes/{route_id_or_name}/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + - $ref: '#/components/parameters/route_id_or_name' + delete: + summary: Delete Filter Chain Associated to a Specific Route + tags: + - filter-chains + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter_chain_id + description: | + Delete filter chain associated to a specific route. + '/services/{service_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + delete: + summary: Delete Filter Chain Associated to a Specific Service + operationId: delete-services-service_id_or_name-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain associated to a specific service. + tags: + - filter-chains + /audit/requests: + get: + summary: List request audit logs + parameters: + - $ref: '#/components/parameters/beforeAuditLogFilter' + - $ref: '#/components/parameters/afterAuditLogFilter' + tags: + - audit-logs + responses: + '200': + $ref: '#/components/responses/audit-objects-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-audit-requests + description: |- + You can access request and database audit logs through the Admin API. + The default order of audit log is by request timestamp - latest to oldest. + For usage examples, see [Audit Logging in Kong Gateway](https://docs.konghq.com/gateway/latest/kong-enterprise/audit-log/). + /audit/objects: + get: + summary: List database audit logs + parameters: + - $ref: '#/components/parameters/beforeAuditLogFilter' + - $ref: '#/components/parameters/afterAuditLogFilter' + responses: + '200': + $ref: '#/components/responses/database-audit-log-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-audit-objects + tags: + - audit-logs + description: List database audit logs (ordered by request timestamp - latest to oldest) + /event-hooks: + get: + summary: List all event hooks + tags: + - Event-hooks + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks + description: List all event hooks and return information about the event hooks. + post: + summary: Add a webhook + operationId: post-event-hooks + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - Event-hooks + description: | + Add a webhook + requestBody: + $ref: '#/components/requestBodies/add-webhook' + /event-hooks/sources: + get: + summary: List all sources + tags: + - Event-hooks + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + balancer: + type: object + properties: + health: + type: object + properties: + fields: + type: array + items: + type: string + crud: + type: object + properties: + acls: + type: object + properties: + fields: + type: array + items: + type: string + rate-limiting-advanced: + type: object + properties: + rate-limit-exceeded: + type: object + properties: + description: + type: string + fields: + type: array + items: + type: string + unique: + type: array + items: + type: string + x-examples: + Example 1: + data: + balancer: + health: + fields: + - upstream_id + - ip + - port + - hostname + - health + crud: + acls: + fields: + - operation + - entity + - old_entity + - schema + rate-limiting-advanced: + rate-limit-exceeded: + description: Run an event when a rate limit has been exceeded + fields: + - consumer + - ip + - service + - rate + - limit + - window + unique: + - consumer + - ip + - service + examples: + sources example: + value: + data: + balancer: + health: + fields: + - string + crud: + acls: + fields: + - string + rate-limiting-advanced: + rate-limit-exceeded: + description: string + fields: + - string + unique: + - string + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks-sources + description: | + Sources are the actions that trigger the event hook. The `/sources` JSON output follows the following pattern: + + * 1st level = The source, which is the action that triggers the event hook. + * 2nd level = The event, which is the Kong entity the event hook listens to for events. + * 3rd level = The available template parameters for use in `webhook-custom` payloads. + + For instance, in the example below `balancer` is the source, `health` is the event, and `upstream_id`, `ip`, `port`, `hostname`, and `health` are the available template parameters. + '/event-hooks/sources/{source}': + parameters: + - schema: + type: string + name: source + in: path + required: true + description: The source you want to list events from. + get: + summary: List all events for a source + tags: + - Event-hooks + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + create: + type: object + properties: + fields: + type: array + items: + type: string + delete: + type: object + properties: + fields: + type: array + items: + type: string + update: + type: object + properties: + fields: + type: array + items: + type: string + x-examples: + Example 1: + data: + create: + fields: + - operation + - entity + - old_entity + - schema + delete: + fields: + - operation + - entity + - old_entity + - schema + update: + fields: + - operation + - entity + - old_entity + - schema + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks-sources-source + description: Events are the Kong entities the event hook listens for events. With this endpoint, you can list all of the events associated with a particular source. + '/event-hooks/{event-hook-id}/test': + parameters: + - schema: + type: string + name: event-hook-id + in: path + required: true + description: The event hook id + post: + summary: Test an event hook + operationId: post-event-hooks-event-hook-id-test + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + It’s useful to manually trigger an event hook without provoking the event to be triggered. For instance, you might want to test the integration, or see if your hook’s service is receiving a payload from Kong. + + POST any data to `/event-hooks/:id-of-hook/test`, and the `/test` endpoint executes the with the provided data as the event payload. + tags: + - Event-hooks + '/event-hooks/{event-hook-id}': + delete: + summary: Delete an event hook + description: Deletes a specific event hook by its ID. + operationId: deleteEventHook + parameters: + - name: event-hook-id + in: path + required: true + description: The ID of the event hook to delete. + schema: + type: string + responses: + '204': + description: Event hook successfully deleted. + '404': + description: Event hook not found. + tags: + - Event-hooks + '/event-hooks/{event-hook-id}/ping': + get: + summary: Ping a webhook event hook + parameters: + - name: event-hook-id + in: path + required: true + description: The ID of the event hook to delete. + schema: + type: string + tags: + - Event-hooks + responses: + '200': + $ref: '#/components/responses/event-hooks-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-event-hooks-event-hook-id-ping + description: | + Ping a webhook event hook. + '/{workspace}/rbac/roles': + parameters: + - schema: + type: string + name: workspace + in: path + required: true + description: The workspace name or UUID. + get: + summary: List roles for a workspace + tags: + - RBAC + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + name: + type: string + next: + type: string + x-examples: + Example 1: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + examples: + Multiple roles: + value: + data: + - comment: 'Full access to all endpoints, across all workspaces—except RBAC Admin API' + created_at: 1557506249 + id: 38a03d47-faae-4366-b430-f6c10aee5029 + name: admin + - comment: 'Read access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 4141675c-8beb-41a5-aa04-6258ab2d2f7f + name: read-only + - comment: 'Full access to all endpoints, across all workspaces' + created_at: 1557506249 + id: 888117e0-f2b3-404d-823b-dee595423505 + name: super-admin + - comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + name: doc_lord + next: null + operationId: get-rbac-roles-by-workspace + description: List all roles by workspace + post: + summary: Add a role + operationId: post-rbac-roles-workspace + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + comment: + type: string + created_at: + type: integer + id: + type: string + is_default: + type: boolean + name: + type: string + x-examples: + Example 1: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + examples: + New role response body: + value: + comment: null + created_at: 1557532241 + id: b5c5cfd4-3330-4796-9b7b-6026e91e3ad6 + is_default: false + name: service_reader + tags: + - RBAC + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + + + description: The RBAC role name. + comment: + type: string + + description: A string describing the RBAC user object. + description: The request body contains the name of the role and an optional attribute. + description: Add a role. + '/{workspace}/rbac/roles/{role}/endpoints/{endpoint}/': + get: + summary: Get role-specific permissions for an endpoint within a workspace + parameters: + - in: path + name: workspace + required: true + schema: + type: string + description: The workspace name or UUID. + - in: path + name: role + required: true + schema: + type: string + description: The RBAC role ID. + - in: path + name: endpoint + required: true + schema: + type: string + description: The specific endpoint to retrieve permissions for. + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + actions: + type: array + items: + type: string + created_at: + type: integer + endpoint: + type: string + negative: + type: boolean + role: + type: object + properties: + id: + type: string + role_source: + description: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + type: string + default: "local" + enum: + - "local" + - "idp" + workspace: + type: string + example: + actions: + - "delete" + - "create" + - "update" + - "read" + created_at: 1557764505 + endpoint: "/consumers" + negative: false + role: + id: "23df9f20-e7cc-4da4-bc89-d3a08f976e50" + workspace: "default" + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: getRoleSpecificEndpointPermissions + tags: + - RBAC + + '/fips-status': + get: + summary: FIPS Mode Status + tags: + - licenses + description: >- + Retrieves the current FIPS mode status. This endpoint indicates whether FIPS mode is active and provides the version of the FIPS module. + responses: + '401': + $ref: '#/components/responses/HTTP401Error' + 200: + description: FIPS mode status retrieved successfully. + content: + application/json: + schema: + type: object + properties: + active: + type: boolean + description: Indicates if FIPS mode is currently active (true) or inactive (false). + version: + type: string + description: The version of the FIPS module, or 'unknown' if the version cannot be determined. + examples: + fips_enabled: + value: {"active": true, "version": "2.0.16"} + summary: FIPS mode is enabled. This may occur after a license configuration change that enables FIPS mode. + fips_disabled: + value: {"active": false, "version": "unknown"} + summary: FIPS mode is disabled or not supported. This may be the default state or result from a license configuration that does not enable FIPS mode. + '/workspace_/groups': + get: + operationId: list-groups + responses: + "200": + content: + application/json: + schema: + items: + properties: + created_at: + format: date-time + type: string + id: + type: string + name: + type: string + type: object + type: array + description: Successfully retrieved the list of groups + summary: Retrieve a list of all groups + tags: + - Workspaces + post: + operationId: create-group + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + required: + - name + type: object + responses: + "201": + content: + application/json: + schema: + properties: + created_at: + format: date-time + type: string + id: + type: string + name: + type: string + type: object + description: Successfully created the group + summary: Create a new group + tags: + - Workspaces + '/workspace_/groups/{groups}': + parameters: + - in: path + name: groups + required: true + schema: + type: string + patch: + operationId: update-group + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + type: object + responses: + "200": + description: Successfully updated the group + summary: Update details of a specific group + tags: + - Workspaces + '/workspace_/groups/{groups}/roles': + delete: + operationId: remove-role-from-group + parameters: + - in: query + name: rbac_role_id + required: true + schema: + type: string + - in: query + name: workspace_id + required: true + schema: + type: string + responses: + "204": + description: Successfully removed the role association + summary: Remove a role association from a group + tags: + - Workspaces + get: + operationId: list-group-roles + responses: + "200": + content: + application/json: + schema: + items: + properties: + group: + properties: + id: + type: string + name: + type: string + type: object + rbac_role: + properties: + id: + type: string + name: + type: string + type: object + workspace: + properties: + id: + type: string + type: object + type: object + type: array + description: Successfully retrieved the roles + summary: Retrieve roles associated with a specific group + tags: + - Workspaces + parameters: + - in: path + name: groups + required: true + schema: + type: string + post: + operationId: add-role-to-group + requestBody: + content: + application/json: + schema: + properties: + rbac_role_id: + type: string + workspace_id: + type: string + required: + - rbac_role_id + - workspace_id + type: object + responses: + "201": + content: + application/json: + schema: + properties: + group: + properties: + id: + type: string + name: + type: string + type: object + rbac_role: + properties: + id: + type: string + name: + type: string + type: object + workspace: + properties: + id: + type: string + type: object + type: object + description: Successfully associated the role with the group + summary: Associate a role with a group + tags: + - Workspaces + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong Gatewat is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong Gatewat is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache + +servers: + - description: Default Admin API URL + url: '{protocol}://{hostname}:{port}{path}' + variables: + hostname: + default: localhost + description: Hostname for Kong's Admin API + path: + default: / + description: Base path for Kong's Admin API + port: + default: '8001' + description: Port for Kong's Admin API + protocol: + default: http + description: Protocol for requests to Kong's Admin API + enum: + - http + - https +security: + - kongAdminToken: [] +tags: + - description: | + Service entities are abstractions of your microservice interfaces or formal APIs. For example, a service could be a data transformation microservice or a billing API. +

+ The main attribute of a service is the destination URL for proxying traffic. This URL can be set as a single string or by specifying its protocol, host, port and path individually. +

+ Services are associated to routes, and a single service can have many routes associated with it. Routes are entrypoints in Kong Gateway which define rules to match client requests. Once a route is matched, Kong Gateway proxies the request to its associated service. See the [Proxy Reference](https://docs.konghq.com/gateway/latest/how-kong-works/routing-traffic/) for a detailed explanation of how Kong proxies traffic. +

+ Services can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). + name: Services + - description: | + Route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to the associated service. You need at least one matching rule that applies to the protocol being matched by the route. +

+ The combination of routes and services, and the separation of concerns between them, offers a powerful routing mechanism with which it is possible to define fine-grained entrypoints in Kong Gateway leading to different upstream services of your infrastructure. +

+ Depending on the protocol, one of the following attributes must be set: +
+ * `http`: At least one of `methods`, `hosts`, `headers`, or `paths` + * `https`: At least one of `methods`, `hosts`, `headers`, `paths`, or `snis` + * `tcp`: At least one of `sources` or `destinations` + * `tls`: at least one of `sources`, `destinations`, or `snis` + * `tls_passthrough`: set `snis` + * `grpc`: At least one of `hosts`, `headers`, or `paths` + * `grpcs`: At least one of `hosts`, `headers`, `paths`, or `snis` + * `ws`: At least one of `hosts`, `headers`, or `paths` + * `wss`: At least one of `hosts`, `headers`, `paths`, or `snis` +
+ + A route can't have both `tls` and `tls_passthrough` protocols at same time. +

+ + Learn more about the router: + * [Configure routes using expressions](https://docs.konghq.com/gateway/latest/key-concepts/routes/expressions/) + * [Router Expressions language reference](https://docs.konghq.com/gateway/latest/reference/expressions-language/) + name: Routes + - description: | + A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. Plugins let you add functionality to services that run behind a Kong Gateway instance, like authentication or rate limiting. + You can find more information about available plugins and which values each plugin accepts at the [Plugin Hub](https://docs.konghq.com/hub/). +

+ When adding a plugin configuration to a service, the plugin will run on every request made by a client to that service. If a plugin needs to be tuned to different values for some specific consumers, you can do so by creating a separate plugin instance that specifies both the service and the consumer, through the service and consumer fields. +

+ Plugins can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). +

+ **Bracket syntax for keys with periods:** + When submitting form data, keys that contain dots (e.g., `service.name`) should be enclosed in square brackets to avoid ambiguity: + + - Example: `config.resource_attributes[service.name]=kong-dev` + + - If necessary, URL encode the square brackets: `%5Bservice.name%5D`. + name: Plugins + - description: | + The consumer object represents a consumer - or a user - of a service. + You can either rely on Kong Gateway as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong Gateway and your existing primary datastore. + name: Consumers + - description: | + A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong Gateway to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. +

+ Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. +

+ If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string. + name: Certificates + - description: | + An SNI object represents a many-to-one mapping of hostnames to a certificate. +

+ A certificate object can have many hostnames associated with it. When Kong Gateway receives an SSL request, it uses the SNI field in the Client Hello to look up the certificate object based on the SNI associated with the certificate. + name: SNIs + - description: | + A target is an IP address or hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. +

+ To disable a target, post a new one with `weight=0`, or use the `DELETE` method to accomplish the same. + name: Targets + - description: | + A CA certificate object represents a trusted certificate authority. + These objects are used by Kong Gateway to verify the validity of a client or server certificate. + name: CA Certificates + - description: | + The upstream object represents a virtual hostname and can be used to load balance incoming requests over multiple services (targets). +

+ An upstream also includes a [health checker](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/), which can enable and disable targets based on their ability or inability to serve requests. + The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + name: Upstreams + - description: | + Vault objects are used to configure different vault connectors for [managing secrets](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/). + Configuring a vault lets you reference secrets from other entities. + This allows for a proper separation of secrets and configuration and prevents secret sprawl. +

+ For example, you could store a certificate and a key in a vault, then reference them from a certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure. +

+ Secrets rotation can be managed using [TTLs](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + name: Vaults + - description: | + A key object holds a representation of asymmetric keys in various formats. When Kong Gateway or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + name: Keys + - description: | + Keyring is the mechanism for storing sensitive data fields, such as consumer secrets, in an encrypted format within the database. This provides for encryption-at-rest security controls in a Kong Gateway cluster. + name: Keyring + - description: | + A JSON Web key set. Key sets are the preferred way to expose keys to plugins because they tell the plugin where to look for keys or have a scoping mechanism to restrict plugins to specific keys. + name: Key-sets + - description: | + The workspace object describes the workspace entity, which has an ID and a name. +

+ Workspaces provide a way to segment Kong Gateway entities. Entities in a workspace are isolated from those in other workspaces. + name: Workspaces + - description: | + A license entity lets you configure a license in your Kong Gateway cluster, in both traditional and hybrid mode deployments. + In hybrid mode deployments, the control plane sends licenses configured through the `/licenses` endpoint to all data planes in the cluster. + The data planes use the most recent `updated_at` license. + name: licenses + - description: | + Consumer groups enable the organization and categorization of consumers (users or applications) within an API ecosystem. + By grouping consumers together, you eliminate the need to manage them individually, providing a scalable, efficient approach to managing configurations. + name: consumer_groups + - description: | + Information routes + name: Information + - description: | + Admin routes + name: admins + - description: | + Group routes + name: groups + - description: | + Debug Routes + name: debug + - description: | + Kong Gateway's RBAC feature is configurable through Kong's Admin API or using Kong Manager. +

+ There are four basic entities involving RBAC: +

+ * User: The entity interacting with the system. Can be associated with zero, one, or more roles. For example: The user `bob` has the token `1234`. + * Role: Set of permissions (`role_endpoint` and `role_entity`). Has a name and can be associated with zero, one, or more permissions. For example: The user `bob` is associated with the role `developer`. + * `role_source`: The origin of the RBAC user role. Specifies where the user role is defined, either locally or through an identity provider (IdP). + * `role_endpoint`: A set of enabled or disabled actions. For example: The role `developer` has one `role_endpoint` and reads and writes to `/routes`. + * `role_entity`: A set of enabled or disabled actions. For example: The role `developer` has one `role_entity` attached to a UUID. + For the admin role in the default workspace, CRUD actions on /groups and /groups/* endpoints are disallowed. + For the workspace-admin role in non-default workspaces, CRUD actions on /groups and /groups/* endpoints are disallowed. + name: RBAC + - description: | + A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + name: filter-chains + - description: | + You can access request and database audit logs through the Admin API. The default order of audit log is by request timestamp - latest to oldest. +

+ For usage examples, see [Audit Logging in Kong Gateway](https://docs.konghq.com/gateway/latest/admin-api/audit-logs/). + name: audit-logs + - description: | + Event hooks are outbound calls from Kong Gateway. With event hooks, the Kong Gateway can communicate with target services or resources, letting the target know that an event was triggered. When an event is triggered in Kong, it calls a URL with information about that event. Event hooks add a layer of configuration for subscribing to worker events using the admin interface. Worker events are integrated into Kong Gateway to communicate within the gateway context. For example, when an entity is created, the Kong Gateway fires an event with information about the entity. Parts of the Kong Gateway codebase can subscribe to these events, then process the events using callbacks. +

+ Depending on the protocol, one of the following attributes must be set: +
+ * `webhook`: Makes a JSON POST request to a provided URL with the event data as a payload. Useful for building a middle tier integration (your own webhook that receives Kong hooks). Specific headers can be configured for the request. + * `webhook-custom`: Fully configurable request. Useful for building a direct integration with a service (for example, a Slack webhook). Because it’s fully configurable, it’s more complex to configure. It supports templating on a configurable body, a configurable form payload, and headers. + * `log`: This handler, which requires no configuration, logs the event and the content of the payload into the Kong Gateway logs. If using hybrid mode, the crud and dao:crud sources will log on the control plane logs and the balancer and rate-limiting-advanced sources will log on the data plane logs. + * `lambda`: This handler runs specified Lua code after an event is triggered. +

+ Event hooks do not work with Konnect yet. +

+ name: Event-hooks + - description: | + Retrieve information about the status of data planes when Kong Gateway is running in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache diff --git a/api-specs/Gateway-OSS/3.8/kong-oss.yaml b/api-specs/Gateway-OSS/3.8/kong-oss.yaml new file mode 100644 index 000000000000..874abf7d52d8 --- /dev/null +++ b/api-specs/Gateway-OSS/3.8/kong-oss.yaml @@ -0,0 +1,8083 @@ +components: + parameters: + pagination-offset: + description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources + in: query + name: offset + schema: + type: string + pagination-size: + description: Number of resources to be returned. + in: query + name: size + schema: + default: 100 + maximum: 1000 + minimum: 1 + type: integer + pagination-tags-filter: + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using ','' to mean AND or using ''/'' to mean OR.' + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + service_id_or_name: + name: service_id_or_name + description: ID **or** name of the service to lookup + example: test-service + in: path + required: true + schema: + type: string + ca_certificate_id: + name: ca_certificate_id + description: ID of the related certificate + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + certificate_id: + name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier of the Certificate to retrieve. + certificate_name_or_id: + name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + sni_name_or_id: + name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + filter_chain_name_or_id: + name: filter_chain_name_or_id + in: path + required: true + schema: + type: string + example: my-filter-chain + description: The unique identifier or name of the Filter Chain to create or update. + plugin_id: + name: plugin_id + in: path + required: true + schema: + type: string + example: response-ratelimiting + description: The unique identifier of the Plugin to create or update. + key-set_id_or_name: + name: key-set_id_or_name + in: path + required: true + schema: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + description: The unique identifier or the `name` attribute of the Key Set that should be associated to the newly-created Key. + key_id_or_name: + name: key_id_or_name + in: path + required: true + schema: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725 + description: The unique identifier or the name of the Key to retrieve. + route_id_or_name: + name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + upstream_id_or_name: + name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + target_id_or_target: + name: target_id_or_target + in: path + required: true + schema: + type: string + example: 'example.com:8000' + description: The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. + vault_id_or_prefix: + name: vault_id_or_prefix + in: path + required: true + schema: + type: string + example: env + description: The unique identifier or the prefix of the Vault to retrieve. + tag: + name: tags + in: path + required: true + schema: + type: string + example: example + description: Tags are strings associated to entities in Kong. + log_level: + name: log_level + in: path + required: true + schema: + type: string + enum: + - info + - notice + - warn + - error + - crit + example: warn + description: Log levels are set in Kong's configuration. Log levels increase in order of their severity + filter_chain_id: + name: filter_chain_id + in: path + required: true + schema: + type: string + description: The unique identifier of the filter chain to retrieve. + schemas: + UnauthorizedError: + type: object + properties: + status: + type: integer + message: + type: string + required: + - status + - message + CA-Certificate: + description: A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate. CA Certificates can be both tagged and filtered by tags. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f260 + type: object + title: CA-Certificate + properties: + cert: + description: PEM-encoded public certificate of the CA. + type: string + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + description: SHA256 hex digest of the public certificate. + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f + format: uuid + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: '["user-level", "low-priority"]' + x-examples: + 200 - list of multiple certificates: + data: + - id: 43429efd-b3a5-4048-94cb-5cc4029909bb + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + - id: d26761d5-83a4-4f24-ac6c-cff276f2b79c + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + Certificate: + description: A certificate object represents a public certificate. These fields are _referenceable_, and can be stored as [secrets](http://docs.konqhq.com/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + type: object + title: Certificate + properties: + cert: + description: PEM-encoded public certificate chain of the SSL key This field is referenceable and can be stored in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + example: '"-----BEGIN CERTIFICATE-----\ncertificate-content\n-----END CERTIFICATE-----"' + cert_alt: + description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs. + type: string + example: '"-----BEGIN CERTIFICATE-----..."' + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + description: The UUID representation of the certificate object. + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + format: uuid + key: + description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + example: ' "-----BEGIN RSA PRIVATE KEY-----..."' + key_alt: + description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + example: '"-----BEGIN EC PRIVATE KEY-----..."' + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: '["user-level", "low-priority"]' + snis: + description: > + A list of SNIs associated with the certificate. + type: array + items: + type: string + format: host + Consumer: + 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. + example: + custom_id: '4200' + id: 8a388226-80e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + 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 + id: + type: string + tags: + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + type: array + username: + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + type: string + type: object + title: Consumer + Filter-chain: + description: A Filter Chain entity represents a list of one or more WebAssembly filters that will be executed during the HTTP request/response lifecycle. + example: + id: "ce44eef5-41ed-47f6-baab-f725cecf98c7" + name: "my-filter-chain" + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: "20487393-41ed-47f6-93a8-3407cade2002" + filters: + - name: "go-rate-limiting" + enabled: true + config: '{ "minute": 30 }' + - name: "rust-response-transformer" + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: ["my-tag"] + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + description: Whether the filter chain is applied. + type: boolean + filters: + description: "An array of filter definitions that will be executed in order." + type: array + items: + type: object + properties: + name: + description: "The name of the filter. This name matches the basename of the WebAssembly module file: for a filter file called `my-filter.wasm`, then filter name will be `my-filter`." + type: string + config: + description: "The configuration for the filter. Proxy-Wasm does not define a configuration format, so this field accepts either a raw string, or a JSON object. A raw string is passed uninterpreted to the filter, to be validated at request time. If a JSON object is used, there must be a metadata file called `my-filter.meta.json` in the same folder as your `my-filter.wasm` file. The metadata file must contain an object with a field `\"config_schema\"`, and its value must the JSON Schema for the filter configuration. This schema will be used for validating the configuration upon insertion in the filter chain, ahead of execution." + oneOf: + - type: string + - type: object + enabled: + description: Whether the filter is to be applied. + type: boolean + id: + type: string + name: + description: The name of the filter chain. + type: string + route: + additionalProperties: false + description: "The route to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: "The service to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Filter Chain for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Filter Chain + Key: + description: A Key object holds a representation of asymmetric keys in various formats. When Kong or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + example: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + type: object + title: Key + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + description: The unique identifier or the prefix of the Vault to delete. + jwk: + description: A JSON Web Key represented as a string. + type: string + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + kid: + description: A unique identifier for a key. + type: string + example: '"42"' + name: + description: The name to associate with the given keys. + type: string + example: a-key + pem: + description: A keypair in PEM format. + type: object + properties: + private_key: + type: string + example: '"-----BEGIN"' + public_key: + type: string + example: '"-----BEGIN"' + set: + additionalProperties: false + description: The id (an UUID) of the key-set with which to associate the key. + type: object + properties: + id: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + tags: + description: An optional set of strings associated with the Key for grouping and filtering. + type: array + items: + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + example: 1422386534 + Key-set: + type: object + title: Key-set + description: A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + description: The unique identifier or the name of the Key to delete. + name: + type: string + description: The name to associate with the given key-set. + example: '"example-key-set"' + tags: + type: array + description: An optional set of strings associated with the Key for grouping and filtering + items: + type: string + example: '["google-keys", "mozilla-keys"]' + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + tags: + - idp-keys + Plugin: + description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. + example: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + properties: + config: + description: The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/). + type: object + consumer: + additionalProperties: false + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the plugin is applied. + type: boolean + id: + type: string + instance_name: + type: string + name: + description: The name of the Plugin thats going to be added. Currently, the Plugin must be installed in every Kong instance separately. + type: string + protocols: + default: + - grpc + - grpcs + - http + - https + description: A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `"tcp"` and `"tls"`. + items: + type: string + type: array + route: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. Leave unset for the plugin to activate regardless of the service being matched. + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Plugin + Route: + description: Route entities define rules to match client requests. Every request matching a given route will be proxied to its associated service. + example: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + type: object + title: Route + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + destinations: + description: A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + type: array + items: + type: object + properties: + '': {} + headers: + description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression. + type: object + hosts: + description: A list of domain names that match this route. Note that the hosts value is case sensitive. + type: array + items: + type: string + example: '"foo.example.com"' + https_redirect_status_code: + default: 426 + description: The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. This config applies only if the route is configured to only accept the `https` protocol. + type: integer + id: + type: string + example: 56c4566c-14cc-4132-9011-4139fcbbe50a + methods: + description: A list of HTTP methods that match this route. + type: array + items: + type: string + name: + description: The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test". + type: string + path_handling: + default: v0 + description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. + type: string + paths: + description: A list of paths that match this route. + type: array + items: + type: string + preserve_host: + default: false + description: When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the services `host`. + type: boolean + protocols: + default: + - http + - https + description: An array of the protocols this route should allow. See the [route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error. + type: array + items: + type: string + regex_priority: + default: 0 + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + type: integer + request_buffering: + default: true + description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. + type: boolean + response_buffering: + default: true + description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. + type: boolean + service: + additionalProperties: false + description: The service this route is associated to. This is where the route proxies traffic to. + type: object + properties: + id: + type: string + expression: + description: The route expression used for advanced routing scenarios. This field is used to evaluate route matches based on complex criteria beyond the standard routing fields. + type: string + priority: + description: A number used to specify the matching order for expression routes. The higher the `priority`, the sooner a route will be evaluated. This field is ignored unless `expression` field is set. The value must be between 0 and 2^46 - 1. + type: integer + default: 0 + snis: + description: A list of SNIs that match this route when using stream routing. + type: array + items: + type: string + sources: + description: A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + type: array + items: + type: object + properties: + '': {} + strip_path: + default: true + description: When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL. + type: boolean + tags: + description: An optional set of strings associated with the route for grouping and filtering. + type: array + items: + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + SNI: + description: An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate. + example: + certificate: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + id: 36c4566c-14cc-4132-9011-4139fcbbe50a + name: some.example.org + type: object + properties: + certificate: + additionalProperties: false + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: + description: The SNI name to associate with the given certificate. + type: string + example: my-sni + tags: + description: An optional set of strings associated with the SNIs for grouping and filtering. + type: array + items: + type: string + example: 'user-level, enterprise' + Service: + description: service entities are abstractions of upstream services. The main attribute of a service is its URL which can be set as a single string or by specifying the `protocol`, `host`, `port` and `path` individually. + example: + host: example.internal + id: 49fd316e-c457-481c-9fc7-8079153e4f3c + name: example-service + path: / + port: 80 + protocol: http + type: object + properties: + ca_certificates: + description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). + type: array + items: + type: string + client_certificate: + additionalProperties: false + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. + type: object + properties: + id: + type: string + connect_timeout: + default: 60000 + description: The timeout in milliseconds for establishing a connection to the upstream server. + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + enabled: + default: true + description: Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). + type: boolean + host: + description: The host of the upstream server. Note that the host value is case sensitive. + type: string + id: + type: string + name: + description: The service name. + type: string + path: + description: The path to be used in requests to the upstream server. + type: string + port: + default: 80 + description: The upstream server port. + type: integer + protocol: + default: http + description: The protocol used to communicate with the upstream. + type: string + read_timeout: + default: 60000 + description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. + type: integer + retries: + default: 5 + description: The number of retries to execute upon failure to proxy. + type: integer + tags: + description: An optional set of strings associated with the service for grouping and filtering. + type: array + items: + type: string + tls_verify: + description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected. + type: boolean + tls_verify_depth: + description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected.' + type: integer + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + url: + description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses. + type: string + write_timeout: + default: 60000 + description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. + type: integer + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + title: Service + Target: + description: A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. To disable a target, post a new one with `weight=0`; alternatively, use the `DELETE` convenience method to accomplish the same. The current target object definition is the one with the latest `created_at`. + example: + id: 089292a7-ba3d-4d88-acf0-97b4b2e2621a + target: 203.0.113.42 + upstream: + id: 5f1d7e76-2fed-4806-a6af-869984f025cb + weight: 100 + type: object + properties: + created_at: + description: Unix epoch when the resource was created. + type: number + example: 1422386534 + id: + type: string + example: 173a6cee-90d1-40a7-89cf-0329eca780a6 + description: The unique identifier or the name of the upstream for which to update the target. + tags: + description: An optional set of strings associated with the Target for grouping and filtering. + type: array + items: + type: string + target: + description: The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record. + type: string + upstream: + additionalProperties: false + type: object + description: The unique identifier or the name of the upstream for which to update the target. + properties: + id: + type: string + example: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + weight: + default: 100 + description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + example: 100 + x-examples: + Example 1: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + created_at: 1422386534 + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + Upstream: + description: The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a service object whose `host` is `service.v1.xyz`. Requests for this service would be proxied to the targets defined within the upstream. An upstream also includes a health check, which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + example: + algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + properties: + algorithm: + default: round-robin + description: Which load balancing algorithm to use. + type: string + client_certificate: + additionalProperties: false + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + hash_fallback: + default: none + description: What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`. + type: string + hash_fallback_header: + description: The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. + type: string + hash_fallback_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + type: string + hash_fallback_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + type: string + hash_on: + default: none + description: What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. + type: string + hash_on_cookie: + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + type: string + hash_on_cookie_path: + default: / + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + type: string + hash_on_header: + description: The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. + type: string + hash_on_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + type: string + hash_on_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + type: string + healthchecks: + properties: + active: + properties: + concurrency: + default: 10 + type: integer + headers: + type: object + healthy: + properties: + http_statuses: + default: + - 200 + - 302 + items: + type: integer + type: array + interval: + default: 0 + type: number + successes: + default: 0 + type: integer + type: object + http_path: + default: / + type: string + https_sni: + type: string + https_verify_certificate: + default: true + type: boolean + timeout: + default: 1 + type: number + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + items: + type: integer + type: array + interval: + default: 0 + type: number + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + passive: + properties: + healthy: + properties: + http_statuses: + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + items: + type: integer + type: array + successes: + default: 0 + type: integer + type: object + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 500 + - 503 + items: + type: integer + type: array + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + threshold: + default: 0 + type: number + type: object + host_header: + description: The hostname to be used as `Host` header when proxying requests through Kong. + type: string + id: + type: string + name: + description: This is a hostname, which must be equal to the `host` of a service. + type: string + slots: + default: 10000 + description: The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`. + type: integer + tags: + description: An optional set of strings associated with the Upstream for grouping and filtering. + items: + type: string + type: array + use_srv_name: + default: false + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`. + type: boolean + type: object + Vault: + description: Vault entities are used to configure different Vault connectors. Examples of Vaults are Environment Variables, HashiCorp Vault and AWS Secrets Manager. Configuring a Vault allows referencing the secrets with other entities. For example a certificate entity can store a reference to a certificate and key, stored in a vault, instead of storing the certificate and key within the entity. This allows a proper separation of secrets and configuration and prevents secret sprawl. + example: + config: + prefix: vaults.config.resurrect_ttl + description: environment variable based vault + id: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + name: env + tags: + - foo + - bar + properties: + config: + description: The configuration properties for the Vault which can be found on the [vaults' documentation page](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + type: object + properties: + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + enum: + - vaults.config.resurrect_ttl + - vaults.config.neg_ttl + - vaults.config.ttl + required: + - prefix + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + description: + description: The description of the Vault entity. + type: string + example: This vault is used to retrieve redis database access credentials + id: + type: string + example: B2A30E8F-C542-49CF-8015-FB674987D1A5 + name: + description: The name of the Vault thats going to be added. Currently, the Vault implementation must be installed in every Kong instance. + type: string + example: env + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + example: env + tags: + description: An optional set of strings associated with the Vault for grouping and filtering. + type: array + items: + type: string + example: database-credentials + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + example: 1422386534 + x-examples: + Example Vault: + id: B2A30E8F-C542-49CF-8015-FB674987D1A5 + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + created_at: 1422386534 + updated_at: 1422386534 + tags: + - database-credentials + - data-plane + Filter-chains: + type: object + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: my-chain + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + - name: go-rate-limiting + enabled: true + config: '{ "minute": 30 }' + - name: rust-response-transformer + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: + - my-tag + description: A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + title: Filter Chains + properties: + id: + type: string + description: The unique identifier or the name attribute of the route that should be associated to the newly created filter chain. + example: ce44eef5-41ed-47f6-baab-f725cecf98c7 + format: uuid + name: + type: string + description: | + The name of the filter chain. + example: my-chain + created_at: + type: integer + example: 1422386534 + updated_at: + type: integer + example: 1422386534 + enabled: + type: boolean + description: | + Whether the filter chain is applied. Default: true. + default: true + route: + description: The route to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `route.id=` or `route.name=`. In JSON format, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: The service to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `service.id=` or `service.name=`. In JSON format, use `"service":{"id":""}` or `"service":{"name":""}`. + example: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + type: array + description: An array of filter definitions. Each filter is an object containing a mandatory name, an optional config, and a boolean enabled setting. + items: + type: object + properties: + name: + type: string + description: | + The name of the filter + example: go-rate-limiting + enabled: + type: boolean + description: Enable the filter + config: + type: string + description: configuration filter headers + example: '{ \"minute\": 30 }' + tags: + type: array + items: + type: string + pagination-offset-response: + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + type: string + requestBodies: + CA-cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: | + PEM-encoded public certificate of the CA. + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + description: | + SHA256 hex digest of the public certificate. + tags: + type: array + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + required: + - cert + description: This request body represents a new Certificate Authority (CA) certificate and includes the properties required to create a new certificate. + cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example: + id: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + key: '-----BEGIN RSA PRIVATE KEY-----...' + cert_alt: '-----BEGIN CERTIFICATE-----...' + key_alt: '-----BEGIN EC PRIVATE KEY-----...' + snis: + - foo.test + - example.com + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: PEM-encoded public certificate chain of the SSL key pair. + example: '"-----BEGIN CERTIFICATE-----...",' + key: + type: string + example: '"-----BEGIN RSA PRIVATE KEY-----..."' + description: PEM-encoded private key of the SSL key pair. + cert_alt: + type: string + description: PEM-encoded public certificate chain of the alternate SSL key pair. + key_alt: + type: string + description: PEM-encoded private key of the alternate SSL key pair. + example: '"-----BEGIN EC PRIVATE KEY-----..."' + snis: + type: array + description: An array of zero or more hostnames to associate with this certificate as SNIs. + items: + type: string + tags: + type: array + description: | + An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + passphrase: + type: string + description: To load an encrypted private key into Kong, specify the passphrase using this attributKong will decrypt the private key and store it in its database. e. Enterprise Only + example: example + required: + - cert + - key + create-sni: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-sni + tags: + - user-level + - low-priority + certificate: + id: a2e013e8-7623-4494-a347-6d29108ff68b + properties: + name: + type: string + description: The SNI name to associate with the given certificate. + example: my-sni + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + example: '["user-level", "low-priority"]' + certificate: + type: object + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is `certificate.id=`. With JSON, use `"certificate":{"id":""}`. + properties: + id: + type: string + example: 91020192-062d-416f-a275-9addeeaffaf2 + description: 91020192-062d-416f-a275-9addeeaffaf2 + required: + - name + - certificate + description: A JSON object containing the details of the new SNI, including the name, certificate, and tags. + consumer-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + username: + type: string + description: | + The unique username of the Consumer. You must send either this field or custom_id with the request. + custom_id: + type: string + 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. + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + required: + - username + - custom_id + description: Consumer request body + filter-chains-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: "ce44eef5-41ed-47f6-baab-f725cecf98c7" + name: "my-filter-chain" + enabled: true + route: null + service: "20487393-41ed-47f6-93a8-3407cade2002" + filters: + - name: "go-rate-limiting" + enabled: true + config: '{ "minute": 30 }' + - name: "rust-response-transformer" + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: ["my-tag"] + properties: + enabled: + description: Whether the filter chain is applied. + type: boolean + example: true + filters: + description: "An array of filter definitions that will be executed in order." + type: array + items: + type: object + properties: + name: + description: "The name of the filter. This name matches the basename of the WebAssembly module file: for a filter file called `my-filter.wasm`, then filter name will be `my-filter`." + type: string + config: + description: "The configuration for the filter. Proxy-Wasm does not define a configuration format, so this field is a raw string, intended to contain the configuration in the format expected by the particular filter in use." + type: string + enabled: + description: Whether the filter is to be applied. + type: boolean + id: + type: string + name: + description: The name of the filter chain. + type: string + example: "my-filter-chain" + route: + additionalProperties: false + description: "The route to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: "The service to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Filter Chain for grouping and filtering. + items: + type: string + type: array + examples: + request example: + value: + id: "ce44eef5-41ed-47f6-baab-f725cecf98c7" + name: "my-filter-chain" + enabled: true + route: null + service: "20487393-41ed-47f6-93a8-3407cade2002" + filters: + - name: "go-rate-limiting" + enabled: true + config: '{ "minute": 30 }' + - name: "rust-response-transformer" + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: ["my-tag"] + description: Filter Chain request body + plugin-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: rate-limiting + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + properties: + name: + type: string + description: | + The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately. + example: rate-limiting + route: + type: string + description: | + If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default: `null`. With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: | + If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: | + If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique globally for Kong Gateway OSS. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the Plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + examples: + request example: + value: + name: rate-limiting + route: string + service: string + consumer: string + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 500 + protocols: + - http + enabled: true + tags: + - string + description: Plugin request body + key-set-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-key_set + tags: + - google-keys + - mozilla-keys + properties: + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + keys-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + properties: + set: + type: object + description: The id (an UUID) of the key-set with which to associate the key .With form-encoded, the notation is `set.id=` or `set.name=`. With JSON, use `"set":{"id":""}` or `"set":{"name":""}.` + properties: + id: + type: string + description: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: + type: string + example: my-key + description: | + The name to associate with the given keys. + kid: + type: string + description: | + A unique identifier for a key. + example: '42' + jwk: + type: string + description: A JSON Web Key represented as a string. + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + pem: + type: object + description: | + A keypair in PEM format. + properties: + private_key: + type: string + example: 'private_key": "-----BEGIN' + public_key: + type: string + example: 'public_key": "-----BEGIN' + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + required: + - kid + route-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + snis: + - foo.test + - example.com + sources: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + destinations: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + properties: + name: + type: string + description: | + The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test". + protocols: + type: array + description: An array of the protocols this route should allow + items: + type: string + default: https + example: tcp + methods: + type: array + description: | + A list of HTTP methods that match this route. + items: + type: string + example: GET + hosts: + type: array + description: A list of domain names that match this route. Note that the hosts value is case sensitive. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array. + items: + type: string + paths: + type: array + description: A list of paths that match this route. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an array. The path can be a regular expression, or a plain text pattern. + items: + type: string + headers: + type: object + description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The Host header cannot be used with this hosts should be specified using the `hosts` attribute. When headers contains only one value and that value starts with the special prefix` ~*`, the value is interpreted as a regular expression. + properties: + x-my-header: + type: array + items: + type: string + x-another-header: + type: array + items: + type: string + https_redirect_status_code: + type: integer + description: |- + The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS` + Location header is injected by Kong if the field is set to `301`, `302`, `307` or `308`. Note: This config applies only if the route is configured to only accept the https protocol. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`. + default: 426 + enum: + - 426 + - 301 + - 302 + - 307 + - 308 + example: 426 + regex_priority: + type: integer + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + default: 0 + example: 0 + strip_path: + type: boolean + description: When matching a route via one of the paths, strip the matching prefix from the upstream request URL. + default: true + path_handling: + type: string + description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. Accepted values are "`v0`", "`v1`". + enum: + - v1 + - v0 + example: v0 + preserve_host: + type: boolean + description: | + When matching a route via one of the `hosts` domain names, use the request `host` header in the upstream request headers. If set to `false`, the upstream Host header will be that of the service's host. + default: true + request_buffering: + type: boolean + default: true + description: | + Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true. + response_buffering: + type: boolean + default: true + description: | + Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: `true`. + snis: + type: array + description: | + A list of SNIs that match this route when using stream routing. + items: + type: string + sources: + type: array + description: | + A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 10.1.0.0/16 + port: + type: integer + example: 1234 + destinations: + type: array + description: | + A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 0.1.0.0/16 + port: + type: integer + tags: + type: array + description: | + An optional set of strings associated with the route for grouping and filtering. + items: + type: string + service: + type: object + description: The service this route is associated to. This is where the route proxies traffic to. With form-encoded, the notation is service.id= or service.name=. With JSON, use `"service":{"id":""}` or `"service":{"name":""}`. + properties: + id: + type: string + example: af8330d3-dbdc-48bd-b1be-55b98608834b + required: + - protocols + - https_redirect_status_code + - preserve_host + - request_buffering + - response_buffering + examples: + Create a route: + value: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + description: Route request body + service-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + properties: + name: + type: string + description: | + The service name. + example: my-service + retries: + type: integer + description: | + The number of retries to execute upon failure to proxy. Default:`5`. + default: 5 + example: 5 + protocol: + type: string + description: |- + The protocol used to communicate with the upstream. Accepted values are: "`grpc`", "`grpcs`", "`http`", "`https`", "`tcp`", "`tls`", "`tls_passthrough`", "`udp`", "`ws`" + , "`wss`" + . Default: "`http`". + default: http + enum: + - grpc + - grpcs + - http + - https + - tcp + - 'tls ' + - tls_passthrough + - udp + - ws + - wss + example: http + host: + type: string + description: | + The host of the upstream server. Note that the host value is case sensitive. + example: example.com + port: + type: integer + description: | + The upstream server port. Default: `80`. + default: 80 + example: 80 + path: + type: string + description: | + The path to be used in requests to the upstream server. + example: /some_api + connect_timeout: + type: integer + description: The timeout in milliseconds for establishing a connection to the upstream server. + default: 6000 + example: 6000 + write_timeout: + type: integer + description: | + The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + read_timeout: + type: integer + description: | + The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + tags: + type: array + description: | + An optional set of strings associated with the service for grouping and filtering. + items: + type: string + example: user-level + client_certificate: + type: object + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is `client_certificate.id=`. With JSON, use `"client_certificate":{"id":""}`. + properties: + id: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: + type: boolean + description: | + Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected. + default: true + tls_verify_depth: + type: string + description: | + Maximum depth of chain while verifying Upstream server's TLS certificate. If set to null, then the Nginx default is respected. Default: null. + example: respected + default: null + nullable: true + ca_certificates: + type: array + description: | + Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to null when Nginx default is respected. + With form-encoded, the notation is `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`. With JSON, use an Array. + items: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: + type: boolean + default: true + description: | + Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`. + required: + - protocol + - host + - port + - enabled + examples: + Example: + value: + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 6000 + write_timeout: 6000 + read_timeout: 6000 + tags: + - user-level + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: true + upstream-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + - x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + properties: + name: + type: string + description: This is a hostname, which must be equal to the `host` of a service. + example: my-upstream + algorithm: + type: string + description: | + Which load balancing algorithm to use. Accepted values are: `"consistent-hashing"`, `"least-connections"`,` "round-robin"`. Default: `"round-robin"`. + enum: + - consistent-hashing + - least-connections + - round-robin + - latency + default: round-robin + example: round-robin + hash_on: + type: string + description: What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + hash_fallback: + type: string + description: What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no Consumer identified). Not available if hash_on is set to cookie. + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + example: none + hash_on_header: + type: string + description: The header name to take the value from as hash input. Only required when `hash_on` is set to header. + example: none + hash_fallback_header: + type: string + description: The header name to take the value from as hash input. Only required when hash_fallback is set to header. + default: none + example: none + hash_on_cookie: + type: string + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + example: none + hash_on_cookie_path: + type: string + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + default: / + example: / + hash_on_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + example: hash_value + hash_fallback_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + example: hash_value + hash_on_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + example: hash_value + hash_fallback_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + example: hash_value + slots: + type: integer + description: The number of slots in the load balancer algorithm. If the algorithm is set to `round-robin`, this setting determines the maximum number of slots. If the algorithm is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range 10-65536. + minimum: 10 + maximum: 65536 + default: 10000 + example: 5000 + healthchecks: + type: object + properties: + passive: + type: object + properties: + type: + type: string + description: Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, http and https options are equivalent. Accepted values are `tcp`, `http`, `https`, `grpc`, `grpcs`. + default: http + enum: + - tcp + - http + - https + - grpc + - grpcs + example: tcp + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=201`. With JSON, use an array. + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + example: + - 200 + - 201 + - 202 + items: + type: integer + enum: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: + type: integer + description: Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks. + default: 0 + example: 2 + unhealthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an array. + default: + - 429 + - 500 + - 503 + example: + - 500 + - 503 + items: + type: integer + enum: + - 429 + - 500 + - 503 + timeouts: + type: integer + description: Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + http_failures: + type: integer + description: Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 3 + tcp_failures: + type: integer + description: Number of TCP connection failures to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + active: + type: object + properties: + https_verify_certificate: + type: boolean + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an array. + default: + - 200 + - 302 + example: + - 200 + - 201 + items: + type: integer + successes: + type: integer + description: Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. + default: 0 + example: 3 + interval: + type: integer + description: Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. + default: 0 + example: 30 + unhealthy: + type: object + properties: + http_failures: + type: integer + description: Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. + default: 0 + example: 2 + http_statuses: + type: array + description: An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=404`. With JSON, use an array. + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + example: + - 400 + - 404 + items: + type: integer + timeouts: + type: integer + description: Number of timeouts in active probes to consider a target unhealthy. + default: 0 + example: 2 + tcp_failures: + type: integer + description: Number of TCP failures in active probes to consider a target unhealthy. + default: 0 + example: 1 + interval: + type: integer + description: Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. + default: 0 + example: 10 + type: + type: string + description: Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. + enum: + - tcp + - http + - https + - grpc + - grpcs + default: http + example: https + concurrency: + type: integer + description: Number of targets to check concurrently in active health checks. + default: 10 + example: 5 + headers: + type: object + description: One or more lists of values indexed by header name to use in GET HTTP request to run as a probe on active health checks. Values must be pre-formatted. + example: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: + type: integer + description: Socket timeout for active health checks (in seconds). + default: 1 + example: 5 + http_path: + type: string + description: Path to use in GET HTTP request to run as a probe on active health checks. + default: / + https_sni: + type: string + description: + The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. + This is particularly useful when Targets are configured using IPs, so that the target host's certificate can be verified with the proper SNI. + threshold: + type: integer + description: The minimum percentage of the upstream's targets' weight that must be available for the whole upstream to be considered healthy. + minimum: 0 + maximum: 100 + default: 0 + tags: + type: array + description: An optional set of strings associated with the Upstream for grouping and filtering. + example: + - user-level + - low-priority + items: + type: string + host_header: + type: string + description: The hostname to be used as Host header when proxying requests through Kong. + client_certificate: + type: object + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + example: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: + type: boolean + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host. + example: false + required: + - name + examples: + Upstream: + value: + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + Example request: + value: + name: my-upstream + tags: + - user-level + - low-priority + algorithm: round-robin + target-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + properties: + target: + default: example.com:8000 + description: The target for the upstream + type: string + weight: + default: 100 + description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + minimum: 0 + maximum: 65535 + tags: + type: array + description: An optional set of strings associated with the Target for grouping and filtering. + items: + type: string + examples: + Example: + value: + target: example.com:8000 + weight: 100 + tags: + - string + vault-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + properties: + prefix: + type: string + description: | + The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + example: env + name: + type: string + description: | + The name of the Vault that's going to be added. Currently, the Vault implementation must be installed in every Kong instance. + example: env + description: + type: string + description: | + The description of the Vault object. + example: This vault is used to retrieve redis database access credentials + config: + type: object + description: | + The configuration properties for the Vault which can be found on the vaults' documentation page. + properties: + prefix: + type: string + example: SSL_ + tags: + type: array + description: | + An optional set of strings associated with the Vault for grouping and filtering. + items: + type: string + examples: + Example 1: + value: + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + responses: + HTTP401Error: + content: + application/json: + examples: + DuplicateApiKey: + summary: Duplicate API key found + value: + message: Duplicate API key found + status: 401 + InvalidAuthCred: + summary: Invalid authentication credentials + value: + message: Unauthorized + status: 401 + NoAPIKey: + summary: No API key found + value: + message: No API key found in request + status: 401 + schema: + $ref: '#/components/schemas/UnauthorizedError' + description: Unauthorized + get-endpoints: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: string + x-examples: + Example 1: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - '/schemas/filters/{name}' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + examples: + Get all endpoints: + value: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + sni-response: + description: SNI response object + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + name: my-sni + created_at: 1422386534 + tags: + - user-level + - low-priority + certificate: + id: a3ad71a8-6685-4b03-a101-980a953544f6 + - id: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: my-sni + created_at: 1422386534 + tags: + - admin + - high-priority + - critical + certificate: + id: 4e8d95d4-40f2-4818-adcb-30e00c349618 + next: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + description: Array of SNIs + items: + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + description: The unique identifier or the name attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + name: + type: string + description: | + The SNI name to associate with the given certificate. + example: my-sni + created_at: + type: integer + example: 1422386534 + description: | + Unix epoch when the resource was created. + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + certificate: + type: object + description: | + The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + properties: + id: + type: string + example: 2e013e8-7623-4494-a347-6d29108ff68b + description: The unique identifier or the name attribute of the Certificate whose SNIs + next: + type: string + example: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + consumer-response-data: + description: The consumer object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + - id: 01c23299-839c-49a5-a6d5-8864c09184af + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier or the name attribute of the consumer. + example: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1422386534 + username: + type: string + description: The unique username of the consumer. You must send either this field or` custom_i`d with the request. + example: my-username + custom_id: + type: string + description: Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. + example: my-custom-id + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + example: admin + next: + type: string + description: Pagination information + example: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + consumer-create-response: + description: New consumer created response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + id: + type: string + description: The unique id of the consumer. + example: c1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: + type: integer + description: | + Unix epoch when the resource was created. + username: + type: string + description: The unique username of the consumer. + custom_id: + type: string + description: Field for the unique consumer ID + tags: + type: array + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + plugin-response: + description: Example response + content: + application/json: + schema: + type: object + properties: + id: + type: string + name: + type: string + description: | + The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately. + example: rate-limiting + created_at: + type: integer + description: Unix epoch when the resource was created. + route: + type: string + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique globally for Kong Gateway OSS. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the Plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + examples: + Plugin response: + value: + data: + - id: 02621eee-8309-4bf6-b36b-a82017a5393e + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + - id: 66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - tcp + - tls + enabled: true + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + key-set-response: + description: Key set object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - idp-keys + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + id: + type: string + example: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + created_at: + type: integer + description: Unix epoch when the resource was last created. + example: 1422386534 + updated_at: + type: integer + description: | + Unix epoch when the resource was last updated. + example: 1422386534 + tags: + type: array + description: | + The name to associate with the given key-set. + items: + type: string + next: + type: string + description: | + Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + example: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + examples: + example: + value: + id: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: my-key_set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - string + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + tags-response: + description: Tags response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - entity_name: services + entity_id: acf60b10-125c-4c1a-bffe-6ed55daefba4 + tag: s1 + offset: c47139f3-d780-483d-8a97-17e9adc5a7ab + next: /tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab + properties: + data: + type: array + items: + type: object + properties: + entity_name: + type: string + example: services + description: The name of the entity that corresponds to a tag + entity_id: + type: string + example: c87440e1-0496-420b-b06f-dac59544bb6c + description: The unique ID for the entity that is attached to the tag + tag: + type: string + example: example + description: The tag + offset: + type: string + example: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + next: + type: string + example: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + examples: + Tags response: + value: + data: + - entity_name: services + entity_id: c87440e1-0496-420b-b06f-dac59544bb6c + tag: example + offset: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + next: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 +externalDocs: + description: Kong Gateway Admin API (OSS) + url: 'https://docs.konghq.com' +info: + contact: + email: docs@konghq.com + name: Kong Inc + url: 'https://konghq.com' + description: |- + OpenAPI 3.0 spec for Kong Gateway's open source Admin API. + + You can know more about Kong Gateway at [docs.konghq.com](https://docs.konghq.com) + .Give Kong a star at [Kong/kong](https://github.com/kong/kong) repository. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + title: Kong Admin API + version: 3.8.0 +openapi: 3.0.0 +paths: + /: + get: + summary: Get Kong's instance information + tags: + - Information + operationId: geInfo + description: | + Returns detailed information about the Kong gateway instance, including the full Kong configuration, available and unavailable plugins, version, edition (enterprise or community), a tagline, the unique node identifier, and other metadata. + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + version: + type: string + description: The version number of the Kong instance. + example: "2.3.3" + edition: + type: string + description: Indicates whether the Kong instance is the Community or Enterprise edition. + example: "Community" + tagline: + type: string + description: A tagline or slogan for the Kong instance. + example: "Welcome to Kong" + node_id: + type: string + description: A unique identifier for the node, in UUID format. + format: uuid + example: "a74d7c4f-ef83-4bbe-a5e7-3f5409f4a0b9" + hostname: + type: string + description: The hostname of the Kong node. + example: "kong-node.example.com" + timers: + type: object + description: Information about running and pending timers. + properties: + running: + type: integer + description: The number of running timers. + example: 5 + pending: + type: integer + description: The number of pending timers. + example: 2 + plugins: + type: object + description: Information about plugins. + properties: + available_on_server: + type: object + additionalProperties: + type: object + properties: + version: + type: string + description: The version of the plugin. + priority: + type: integer + description: The priority of the plugin. + enabled_in_cluster: + type: array + items: + type: string + description: A list of distinct plugin names enabled in the cluster. + example: ["jwt", "acl"] + lua_version: + type: string + description: The version of Lua used by the Kong instance. + example: "LuaJIT 2.1.0-beta3" + configuration: + type: object + description: A sanitized version of the Kong configuration, excluding sensitive values. + additionalProperties: true + pids: + type: object + description: Process IDs for the master process and worker processes. + properties: + master: + type: integer + description: The PID of the master process. + example: 4321 + workers: + type: array + items: + type: integer + description: An array of worker process PIDs. + example: [1234, 5678] + examples: + openSourceExample: + summary: Open Source Edition Example Response + value: + configuration: + _debug_pg_ttl_cleanup_interval: 300 + admin_acc_logs: "/usr/local/kong/logs/admin_access.log" + admin_access_log: "/dev/stdout" + edition: "community" + hostname: "b8f553cfbd0c" + lua_version: "LuaJIT 2.1.0-20230410" + node_id: "39bfa49d-3394-4f8e-b9db-94b786bc4e5f" + pids: + master: 1 + workers: [1278, 1279, 1280, 1281, 1282, 1283, 1284, 1285] + plugins: + available_on_server: + acl: + priority: 950 + version: "3.6.0" + enabled_in_cluster: [] + tagline: "Welcome to kong" + timers: + pending: 1 + running: 145 + version: "3.6.0" + '401': + $ref: '#/components/responses/HTTP401Error' + '405': + description: Method Not Allowed + content: + application/json: + schema: + $ref: '#/components/schemas/UnauthorizedError' + headers: + Server: + description: Kong's server tokens. + schema: + type: string + example: "kong/2.3.3" + /ca_certificates: + get: + description: Retrieve a list of all available Certificate Authority (CA) certificates, including the certificate ID, creation date, and other details. You can use query parameters to filter the results by size or tags, for example `/ca-certificates?size=50&tags=enterprise`. + operationId: list-ca_certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + examples: {} + text/plain: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: A successful response listing CA Certificates + summary: List all CA certificates + tags: + - CA Certificates + post: + description: Create a new Certificate Authority (CA) certificate. The request body must include the `cert` property, the certificate data in PEM format; it can also include `cert_digest`, a digest of the certificate in hex format for verifying the certificates integrity, and `tags`, an optional list of tags to categorize the certificate. + operationId: create-ca_certificate + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: The created certificate object. + '400': + description: Invalid CA certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new CA certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + '/ca_certificates/{ca_certificate_id}': + delete: + description: Delete the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. + operationId: delete-ca_certificate + responses: + '204': + description: Successfully deleted CA Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a CA Certificate + tags: + - CA Certificates + get: + description: Retrieve details about the specified Certificate Authority (CA) certificate using the provided path parameter `ca_certificate_id`. + operationId: get-ca_certificate + parameters: + - description: The unique identifier of the certificate to retrieve. + in: path + name: ca_certificate_id + required: true + schema: + type: string + examples: + example: + summary: Example CA certificate ID + value: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: The specified CA certificate exists in the system, and the response includes details about the certificate. + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a CA certificate + tags: + - CA Certificates + patch: + description: |- + Update the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. Use this endpoint to modify an existing CA certificate in the system. The request body should include the fields of the CA certificate that need to be updated. + + > This API is not available in DB-less mode. + operationId: update-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully updated CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + put: + description: Create or Update a CA Certificate using the provided path parameter `ca_certificate_id`. + operationId: updatet-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully upserted CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + parameters: + - $ref: '#/components/parameters/ca_certificate_id' + /certificates: + get: + description: Retrieve a list of all available CA Certificate Authority (CA) certificates. You can use query parameters to filter the results by size or tags, for example `/certificates?size=50&tags=enterprise`. + operationId: list-certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Certificate' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all certificates + tags: + - Certificates + post: + description: |- + Create a new certificate with the provided details. Use this endpoint to add a new certificate to the system. The request body must include the certificate data and other details required for creating a new certificate. + + > Note: This API is not available in DB-less mode. + operationId: create-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + '/certificates/{certificate_id}': + delete: + description: | + Delete a Certificate + + >Note: This API is not available in DB-less mode. + operationId: delete-certificate + parameters: + - description: ID of the Certificate to delete + in: path + name: certificate_id + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Certificate + tags: + - Certificates + get: + description: Retrieve details about the specified certificate using the provided path parameter `certificate_id`. + operationId: get-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: HTTP 200 OK + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Certificate + tags: + - Certificates + patch: + description: |- + Update a Certificate + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + + >Note: This API is not available in DB-less mode. + operationId: update-certificate + parameters: + - description: ID of the Certificate to update + in: path + name: certificate_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + put: + description: | + Update details about the specified certificate using the provided path parameter `certificate_id`. + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + + + + > Note: This API is not available in DB-less mode. + operationId: update-certificate-put + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/certificate_id' + '/certificates/{certificate_name_or_id}/snis': + get: + description: Retrieve a paginated list of all SNIs associated with a certificate. Use this endpoint to retrieve a list of SNIs that are linked to a specific certificate. You can use the optional query parameters to filter the results based on specific criteria. The response will include the list of SNIs and pagination information. See the response schema for details on the expected format of the response body. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List SNIs associated with a certificate + tags: + - SNIs + operationId: get-sni-with-certificate + post: + description: Create a new SNI and associate it with a certificate in the system. Use this endpoint to add a new SNI to the system and link it to a specific certificate. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully created SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI associated with a Certificate + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: create-sni-for-certificate + parameters: + - $ref: '#/components/parameters/certificate_name_or_id' + '/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: | + Delete a an SNI associated with a Certificate using ID or name. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a an SNI associated with a Certificate + tags: + - SNIs + operationId: delete-sni-for-certificate + get: + description: Get an SNI associated with a Certificate using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully fetched SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI associated with a certificate + tags: + - SNIs + operationId: fetch-sni-with-certificate + patch: + description: |2 + + + + Update an existing SNI associated with a certificate in the system using the SNI ID or name. The request body should include the fields of the SNI that need to be updated, such as the name, description, or other properties. If the request body contains valid data, the endpoint will update the SNI and return a success response. + + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully updated SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update SNI associated to a certificate + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: update-sni-for-certificate + put: + description: | + Create or Update an SNI associated with a Certificate using ID or name. + + Inserts (or replaces) the SNI under the requested resource with the definition specified in the body. The SNI will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the SNI being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new SNI without specifying id (neither in the URL nor in the body), then it will be auto-generated. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully upserted SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert an SNI associated with a certificate + tags: + - SNIs + operationId: upsert-sni-for-certificate + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier of the Certificate to retrieve. + - name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + /consumers: + get: + description: Retrieve a list of all consumers.You can use query parameters to filter the results by size or tags, for example `/consumers?size=50&tags=enterprise`. + operationId: list-consumer + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Consumer' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Consumers + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Consumers + tags: + - Consumers + post: + description: Create a new Consumer + operationId: create-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully created Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + '/consumers/{consumer_username_or_id}': + delete: + description: Delete a specific consumer from the system using either the consumer ID or the consumer username. This operation is irreversible and permanently removes all data associated with the specified consumer. If the consumer was deleted succesfully the endpoint will return a 204 response indicating that the resource did not exist. + operationId: delete-consumer + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Consumer + tags: + - Consumers + get: + description: Retrieve the details of a specific consumer in the system using either the consumer ID or the consumer username. If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: get-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully fetched Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Consumer + tags: + - Consumers + patch: + description: Update the details of a specific consumer in the system using either the consumer ID or the consumer username.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: update-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully updated Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: |- + Create or Update Consumer using ID or username. The consumer will be identified via the username or id attribute.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + + When the username or id attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its id. Otherwise it will be identified by its username. + + When creating a new Consumer without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a username in the URL and a different one in the request body is not allowed. + + > Note: This API is not available in DB-less mode. + operationId: upsert-consumer + responses: + '200': + $ref: '#/components/responses/consumer-response-data' + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Not Found + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + '/consumers/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: List all plugins associated with a consumer + tags: + - Plugins + operationId: list-plugins-for-consumer + post: + description: Create a new Plugin associated with a Consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-consumer + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_username_or_id}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a Consumer using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Plugin associated with a Consumer + tags: + - Plugins + operationId: delete-plugin-for-consumer + get: + description: Get a Plugin associated with a Consumer using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a Consumer + tags: + - Plugins + operationId: fetch-plugin-for-consumer + patch: + description: Update a Plugin associated with a consumer using the consumer username or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-consumer + put: + description: Create or Update a Plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-consumer + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + - $ref: '#/components/parameters/plugin_id' + /key-sets: + get: + description: | + Retrieve a list of all Key-sets in the system. A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. Key Sets can be both tagged and filtered by tags. + operationId: list-key-set + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Key-sets + tags: + - Key-sets + post: + description: This endpoint allows creating a new Key-set by sending a JSON object that describes the Key-set to be created.The request body must contain all the fields required to create a new Key-set. + operationId: create-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + description: Returned if the request contains invalid data. + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + '/key-sets/{key-set_id_or_name}': + delete: + description: |- + Delete a Key-set + + > Note: This API is not available in DB-less mode. + operationId: delete-key-set + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key-set + tags: + - Key-sets + get: + description: This endpoint retrieves information about a specific key-set based on its ID or name. + operationId: get-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Key-set + tags: + - Key-sets + patch: + description: |- + Update a Key-set using ID or name. + + > Note: This API is not available in DB-less mode. + + Inserts (or replaces) the Key Set under the requested resource with the definition specified in the body. The Key Set will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the Key Set being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new Key Set without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + operationId: update-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: |- + Update a Key-set using ID or name. + + > Note: This API is not available in DB-less mode. + operationId: upsert-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/key-set_id_or_name' + /keys: + get: + description: List all Keys + operationId: list-key + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Key' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Keys + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Keys + tags: + - Keys + post: + description: | + This API endpoint allows you to create a new key. When the request is successful, the API will respond with a 200 status code and a JSON object that represents the newly created key. If the request is invalid, the API will respond with a `400` status code and an error message in the response body. + + > Note: This API is not available in DB-less mode. + operationId: create-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + '/keys/{key_id_or_name}': + delete: + description: Delete a Key + operationId: delete-key + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key + tags: + - Keys + get: + description: Get a Key using ID or name. + operationId: get-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + example: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully fetched Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Key + tags: + - Keys + patch: + description: Update a Key + operationId: update-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example: + value: + id: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + created_at: 1422386534 + updated_at: 1422386534 + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: Create or Update Key using ID or name. + operationId: upsert-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/key_id_or_name' + /plugins: + get: + description: This endpoint allows you to list all the plugins. You can use query parameters to filter the results by size or tags, for example `/plugins?size=50&tags=enterprise`. + operationId: list-plugin + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Plugins + tags: + - Plugins + post: + description: |- + Create a new Plugin + + >Note: This API is not available in DB-less mode. + operationId: create-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + '/plugins/{plugin_id}': + delete: + description: Delete a Plugin + operationId: delete-plugin + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Plugin + tags: + - Plugins + get: + description: Get a Plugin using ID. + operationId: get-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Plugin + tags: + - Plugins + patch: + description: Update a Plugin + operationId: update-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update Plugin using ID. + operationId: upsert-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/plugin_id' + /routes: + get: + description: |- + List all routes + + route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to its associated service. + + > Note: Path handling algorithms v1 was deprecated in Kong 3.0. From Kong 3.0, when router_flavor is set to expressions, route.path_handling will be unconfigurable and the path handling behavior will be "v0"; when router_flavor is set to traditional_compatible, the path handling behavior will be "v0" regardless of the value of route.path_handling. Only router_flavor = traditional will support path_handling "v1" behavior. + operationId: list-route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes + tags: + - Routes + post: + description: Create a new route + operationId: create-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + '/routes/{route_id_or_name}': + delete: + description: |- + Delete a route + + + > Note: This API is not available in DB-less mode. + operationId: delete-route + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route + tags: + - Routes + get: + description: Get a route using ID or name. + operationId: get-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route + tags: + - Routes + patch: + description: |- + Update a route + + > Note: This API is not available in DB-less mode. + operationId: update-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: |- + Create or Update route using ID or name. + + + > Note: This API is not available in DB-less mode. + operationId: upsert-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins': + get: + description: List all Plugins associated with a route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Plugins associated with a route + tags: + - Plugins + operationId: list-plugins-for-route + post: + description: Create a new Plugin associated with a route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully created Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Create a new Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-route + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + '/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a route using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Plugin associated with a route + tags: + - Plugins + operationId: delete-plugin-for-route + get: + description: Get a Plugin associated with a route using ID. + parameters: + - description: ID or name of the related route + in: path + name: route_id_or_name + required: true + schema: + type: string + - description: ID of the route to lookup + in: path + name: plugin_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a route + tags: + - Plugins + operationId: fetch-plugin-for-route + patch: + description: Update a Plugin associated with a route using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-route + put: + description: Create or Update a Plugin associated with a route using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + /services: + get: + description: List all services + operationId: list-service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + application/xml: + schema: + type: object + properties: {} + description: A successful response listing services + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all services + tags: + - Services + post: + description: Create a new service + operationId: create-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + '/services/{service_id_or_name}': + delete: + description: Delete a service + operationId: delete-service + parameters: + - description: ID or name of the service to delete + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted service or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a service + tags: + - Services + get: + description: Get a service using ID or name. + operationId: get-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a service + tags: + - Services + patch: + description: Update a service + operationId: update-service + parameters: + - description: ID or name of the service to update + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update service using ID or name. + operationId: upsert-service + parameters: + - description: Name or ID of the service to lookup + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}plugins': + get: + description: List all Plugins associated with a service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Plugins + summary: List all Plugins associated with a service + tags: + - Plugins + operationId: get-plugins-for-service + post: + description: Create a new Plugin associated with a service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a service using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a service + tags: + - Plugins + operationId: delete-plugin-for-a-service + get: + description: Get a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Plugin associated with a service + tags: + - Plugins + operationId: fetch-plugin-with-a-service + patch: + description: Update a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-a-service + put: + description: Create or Update a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-a-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a service + parameters: + - description: ID or name of the related service + in: path + name: service_id_or_name + required: true + schema: + type: string + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + examples: + Example 1: + value: + data: + - hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + offset: string + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes associated with a service + tags: + - Routes + operationId: list-routes-for-service + post: + description: Create a new route associated with a service + parameters: + - description: ID or name of the related service + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + example: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a service using ID or name. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route associated with a service + tags: + - Routes + operationId: delete-route-for-service + get: + description: Get a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route associated with a service + tags: + - Routes + operationId: fetch-route-for-service + patch: + description: Update a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-for-service + put: + description: Create or Update a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + /snis: + get: + description: List all SNIs + operationId: list-sni + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs + tags: + - SNIs + post: + description: Create a new SNI + operationId: create-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + '/snis/{sni_name_or_id}': + delete: + description: Delete an SNI + operationId: delete-sni + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an SNI + tags: + - SNIs + get: + description: Get an SNI using ID or name. + operationId: get-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI + tags: + - SNIs + patch: + description: Update an SNI + operationId: update-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name. + operationId: upsert-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/sni_name_or_id' + /upstreams: + get: + description: | + List all registered upstreams. You can filter the results by pagination size, offset, or tags like `/upstreams?size=10&offset=0`. + operationId: list-upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + examples: + example: + value: + data: + - algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + offset: string + description: A successful response listing Upstreams + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Upstreams + tags: + - Upstreams + post: + description: | + Create a new Upstream + operationId: create-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + '/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream + operationId: delete-upstream + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an Upstream + tags: + - Upstreams + get: + description: Get an Upstream using ID or name. + operationId: get-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an Upstream + tags: + - Upstreams + patch: + description: Update an Upstream + operationId: update-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + examples: + Example 1: + value: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name. + operationId: upsert-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + examples: + Example 1: + value: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream + parameters: + - description: ID or name of the related Upstream + in: path + name: upstream_id_or_name + required: true + schema: + type: string + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Target' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Targets + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Targets associated with an Upstream + tags: + - Targets + operationId: list-targets-for-upstream + post: + description: Create a new Target associated with an Upstream + parameters: + - description: ID or name of the related Upstream + in: path + name: upstream_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + examples: + Successfully created Target: + value: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + created_at: 1422386534 + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-for-upstream + parameters: + - name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + '/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Target associated with a an Upstream + tags: + - Targets + operationId: delete-upstream-target + get: + description: Get a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream + tags: + - Targets + operationId: fetch-target-for-upstream + patch: + description: Update a Target associated with a an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-for-upstream + put: + description: Create or Update a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-for-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + /vaults: + get: + description: List all Vaults + operationId: list-vault + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Vaults + tags: + - Vaults + post: + description: Create a new Vault + operationId: create-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + '/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault + operationId: delete-vault + parameters: + - description: ID or prefix of the Vault to delete + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Vault + tags: + - Vaults + get: + description: |- + Get a Vault using ID or prefix. + + Vault entities are used to configure different Vault connectors. + operationId: get-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Vault + tags: + - Vaults + patch: + description: Update a Vault + operationId: update-vault + parameters: + - description: ID or prefix of the Vault to update + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix. + operationId: upsert-vault + parameters: + - description: Name or ID of the Vault to lookup + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/vault_id_or_prefix' + /endpoints: + get: + summary: List all endpoints + tags: + - Information + responses: + '200': + $ref: '#/components/responses/get-endpoints' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-endpoints + description: List all available endpoints provided by the Admin API. + '/{endpoint}': + parameters: + - schema: + type: string + example: key + name: endpoint + in: path + required: true + description: Any available endpoint + head: + summary: Check endpoint or entity existence + operationId: head-endpoints + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:38:29 GMT' + Content-Type: + description: The media type of the message content + schema: + type: string + example: text/html; charset=UTF-8 + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: aqETeVmkeiGnAMzdUT2JRWroB2myY1lB + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Endpoint does not exist + headers: {} + description: | + Similar to `HTTP` GET, but does not return the body. Returns HTTP 200 when the endpoint exits or HTTP 404 when it does not. Other status codes are possible. + tags: + - Information + options: + summary: List method by endpoint + operationId: options-endpoint + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:24:17 GMT' + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + Access-Control-Allow-Headers: + description: Used in response to a preflight request to indicate which HTTP headers can be used during the actual request + schema: + type: string + example: 'Content-Type, Kong-Admin-Token, Kong-Request-Type, Cache-Control' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: gDP1cF3OsNbrgcKPhRNE0RXRNfS7NcoG + Allow: + description: Lists the HTTP methods that are supported for the resource + schema: + type: string + example: 'OPTIONS, PATCH, POST' + Access-Control-Allow-Methods: + description: Indicates the methods allowed when accessing the resource in response to a preflight request + schema: + type: string + example: 'OPTIONS, PATCH, POST' + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request. + tags: + - Information + '/schemas/{entity}': + parameters: + - schema: + type: string + name: entity + in: path + required: true + get: + summary: Retrieve entity schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + - id: + auto: true + type: string + uuid: true + properties: + fields: + type: array + description: A value of a schema + items: + type: object + properties: + id: + type: object + description: A value of a schema + properties: + auto: + type: boolean + description: A value of a schema + type: + type: string + description: A value of a schema + uuid: + type: boolean + description: A value of a schema + examples: + A mock schema: + value: + fields: + - id: + auto: true + type: string + uuid: true + - created_at: + auto: true + timestamp: true + type: integer + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-entity + description: Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations with Kong. + '/schemas/{entity}/validate': + parameters: + - schema: + type: string + name: entity + in: path + required: true + post: + summary: Validate a configuration against a schema + operationId: post-schemas-entity-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + Message: + type: string + example: schema validation successful + description: A success message + examples: + schema validation successful: + value: + Message: schema validation successful + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + tags: + - Information + '/schemas/filters/{filter_name}': + parameters: + - schema: + type: string + example: go-rate-limiting + name: filter_name + in: path + required: true + description: The name of a Proxy-Wasm filter + get: + summary: Retrieve Proxy-Wasm Filter JSON Schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + description: | + JSON Schema object describing the expected configuration for the filter. This endpoints always returns a JSON Schema object describing the filter configuration, even if the filter does not include JSON Schema metadata: if the configuration is expected as a raw string, the JSON Schema configuration returned by this endpoint will indicate so. + examples: + filter returning a JSON Schema included in the filter metadata: + value: + $schema: "http://json-schema.org/draft-04/schema#" + type: "object" + properties: + add: + type: "object" + properties: + headers: + type: "array" + items: + type: "string" + required: [headers] + required: [add] + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-filters-filter_name + description: | + Retrieve the JSON Schema of a Proxy-Wasm filter's configuration. This is useful to understand what fields a filter accepts, and can be used for building third-party integrations to the Kong's filter chain system. + '/schemas/plugins/{plugin_name}': + parameters: + - schema: + type: string + example: basic-auth + name: plugin_name + in: path + required: true + description: The name of a Kong plugin + get: + summary: Retrieve Plugin Schema + tags: + - Information + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-plugins-plugin_name + description: | + Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system. + /schemas/plugins/validate: + post: + summary: Validate plugin schema + operationId: post-schemas-plugins-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: schema validation successful + properties: + message: + type: string + description: A successful message + example: schema validation successful + examples: + schema validation successful: + value: + message: schema validation successful + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + + This only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + tags: + - Information + /timers: + get: + summary: Retrieve Runtime Debugging Info of Kong's Timers + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + stats: + sys: + total: 13 + waiting: 12 + runs: 6771 + pending: 0 + running: 1 + flamegraph: + pending: '' + running: '' + elapsed_time: '' + timers: + router-rebuild: + is_running: false + name: router-rebuild + stats: + runs: 464 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 464 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off': + is_running: false + name: 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off' + stats: + runs: 3 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 3 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + worker: + id: 0 + count: 5 + properties: + stats: + type: object + description: Statistics about the worker + properties: + sys: + type: object + description: List of the number of different type of timers + properties: + total: + description: The total number of timers (running + pending + waiting) + type: integer + default: 7 + example: 7 + waiting: + description: The number of unexpired timers + type: integer + default: 7 + example: 7 + runs: + description: The total number of runs for the timers + type: integer + default: 7 + example: 7 + pending: + description: The number of pending timers + type: integer + default: 0 + example: 0 + running: + description: The number of running timers + type: integer + default: 0 + example: 0 + flamegraph: + type: object + description: String-encoded timer-related flamegraph data + properties: + pending: + description: The number of pending timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + running: + description: The number of running timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + elapsed_time: + description: The elapsed time for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17 + timers: + description: Timer statistics for the worker + type: object + properties: + meta: + description: Program callstack of created timers + type: object + properties: + name: + description: The name of the timer's metadata + type: string + example: '@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()' + worker: + type: object + properties: + id: + type: integer + description: The ordinal number of the current Nginx worker processes (starting from number 0). + count: + type: integer + description: The total number of the Nginx worker processes. + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-timers + description: Retrieve runtime stats data from [lua-resty-timer-ng](https://github.com/Kong/lua-resty-timer-ng). + /status: + get: + summary: Health Routes + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + properties: + memory: + type: object + description: Metrics about the memory usage. + properties: + lua_shared_dicts: + type: object + description: An array of information about dictionaries that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (capacity) and how much of said memory is in use (allocated_slabs). + properties: + kong_core_db_cache: + type: object + properties: + capacity: + type: string + example: 128.00 MiB + description: Memory capacity + allocated_slabs: + type: string + example: 128.00 MiB + description: Total allocated memory + workers_lua_vms: + type: array + description: An array with all workers of the Kong node, each entry contains a `http_allocated_gc` string and a `pid`. + items: + type: object + properties: + http_allocated_gc: + type: string + description: | + HTTP submodule's Lua virtual machine's memory usage information, as reported by + pid: + type: integer + description: worker's process identification number. + example: 18478 + database: + type: object + description: Metrics about the database + properties: + reachable: + type: boolean + description: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself. + server: + type: object + description: Metrics about the nginx HTTP/S server + properties: + connections_reading: + type: integer + description: The current number of connections where Kong is reading the request header. + example: 3 + connections_writing: + type: integer + description: The current number of connections where nginx is writing the response back to the client. + example: 1 + total_requests: + type: integer + description: The total number of client requests. + example: 1 + connections_waiting: + type: integer + description: The current number of idle client connections waiting for a request. + example: 1 + connections_handled: + type: integer + description: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached. + example: 1 + connections_active: + type: integer + description: The current number of active client connections including Waiting connections. + example: 1 + connections_accepted: + type: integer + description: The total number of accepted client connections. + example: 1 + examples: + Status endpoint response: + value: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-status + description: |- + Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, the status of the database connection, and node's memory usage. + + If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used. + /status/dns: + get: + summary: DNS Status + tags: + - Information + operationId: getDnsStatus + description: | + Retrieve DNS worker and stats information. If the legacy DNS client is in use, it returns a 501 status with a message. + responses: + '200': + description: DNS worker and stats information + content: + application/json: + schema: + type: object + properties: + worker: + type: object + description: Worker information. + properties: + id: + type: integer + description: The worker ID. + example: 1 + count: + type: integer + description: The total number of workers. + example: 4 + stats: + type: object + description: DNS stats information (specific details depend on the Kong instance). + '501': + description: Legacy DNS client in use + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Message indicating that the endpoint is not implemented with the legacy DNS client. + example: "not implemented with the legacy DNS client" + '401': + $ref: '#/components/responses/HTTP401Error' + /tags: + get: + summary: List all tags + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags + description: |- + Returns a paginated list of all the tags in the system. + + The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list. + + If an entity is tagged with more than one tag, the entity_id for that entity will appear more than once in the resulting list. Similarly, if several entities have been tagged with the same tag, the tag will appear in several items of this list. + '/tags/{tags}': + parameters: + - $ref: '#/components/parameters/tag' + get: + summary: List entity by tag + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags-tags + description: |- + Returns the entities that have been tagged with the specified tag. + + The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list. + '/debug/cluster/control-planes-nodes/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set Node Log Level of All Control Plane Nodes + operationId: put-debug-cluster-control-planes-nodes-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + description: Response message + example: log level changed + examples: + log level changed: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Change the log level of all control plane nodes deployed in a hybrid (CP/DP) cluster. + + See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. + + Care must be taken when changing the log level of a node to `debug` in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level such as notice. + + It's currently not possible to change the log level of DP and DB-less nodes. + tags: + - Debug + '/debug/cluster/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set Node Log Level of All Nodes + operationId: put-debug-cluster-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + example: log level changed + description: A message containing information about the log level + examples: + log level changed: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Change the log level of all nodes in a cluster. + + + + See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. + + It's currently not possible to change the log level of DP and DB-less nodes. + + Currently, when a user dynamically changes the log level for the entire cluster, if a new node joins a cluster the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. + tags: + - Debug + /debug/node/log-level: + get: + summary: Retrieve Node Log Level of A Node + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: 'log level: debug' + properties: + message: + type: string + example: 'log level: debug' + description: A message containing the current log level of the node. + examples: + Example 1: + value: + message: 'log level: debug' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-debug-node-log-level + description: |- + Retrieve the current log level of a node. + + See the [NGINX documentation](http://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + tags: + - Debug + parameters: [] + '/debug/node/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set log level of a single node + operationId: put-debug-node-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + description: A message confirming the log level change + example: log level changed + examples: + log level changed: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Change the log level of a node. + + See the [NGINX documentation](http://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + tags: + - Debug + '/schemas/vaults/{vault_name}': + parameters: + - schema: + type: string + name: vault_name + in: path + required: true + description: The vault schema to be returned + get: + summary: Retrieve Vault Schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: No vault named + operationId: get-schemas-vaults-vault_name + description: Retrieve the schema of a vault. + post: + summary: Validate Vault Schema + tags: + - Validation + requestBody: + description: Payload containing the schema data to validate + required: true + content: + application/json: + schema: + type: object + properties: + schemaData: + type: string + description: JSON string containing the vault schema data + responses: + '200': + description: Validation successful + content: + application/json: + schema: + type: object + properties: + validation: + type: boolean + description: Indicates if the schema is valid + '400': + description: Bad request due to invalid schema data + '405': + description: Method Not Allowed + operationId: post-schemas-vaults-validate + description: Validates the given vault schema data against predefined validation rules. + /filter-chains: + post: + summary: Add Filter Chain + operationId: post-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Create Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains + operationId: get-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + List All Filter Chains + '/routes/{route_id_or_name}/filter-chains': + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + post: + summary: Add Filter Chain + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_name_or_id-filter-chains + description: | + Create Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Route + operationId: get-routes-route_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + tags: + - filter-chains + description: | + List Filter Chains Associated to a Specific Route + patch: + summary: Update Filter Chain Associated to a Specific Route + operationId: patch-routes-route_id_or_name-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + '/services/{service_id_or_name}/filter-chains': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + post: + summary: Create Filter Chain Associated to a Specific Service + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-services-service_id_or_name-filter-chains + description: | + Add filter chain Associated to a Specific Service + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Service + operationId: get-service_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List Filter Chains Associated to a Specific Service + tags: + - filter-chains + '/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: Retrieve Filter Chain + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + operationId: get-filter-chains-filter_chain_id + description: | + Retrieve Filter Chain + '401': + $ref: '#/components/responses/HTTP401Error' + patch: + summary: Update Filter Chain + operationId: patch-filter-chains-filter_chain_id + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + put: + summary: Update Or Create Filter Chain + operationId: put-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: |- + Inserts (or replaces) the filter chain under the requested resource with the definition specified in the body. The filter chain is identified via the name or ID attribute. + + When the name or ID attribute has the structure of a UUID, the filter chain being inserted or replaced is identified by its ID. Otherwise, it is identified by its name. + + When creating a new filter chain without specifying an ID (neither in the URL nor in the body), the ID will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + delete: + summary: Delete Filter Chain + operationId: delete-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain. + tags: + - filter-chains + '/routes/{route_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: List Filter Chains Associated to a Specific Route + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter-chains-filter_chain_id + description: | + Retrieve filter chain associated to a specific route. + put: + summary: Create Or Update Filter Chain Associated to a Specific Route + operationId: put-routes-route_id_or_name-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Create or update filter chain associated to a specific route. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + tags: + - filter-chains + '/routes/{route_id_or_name}/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + - $ref: '#/components/parameters/route_id_or_name' + delete: + summary: Delete Filter Chain Associated to a Specific Route + tags: + - filter-chains + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter_chain_id + description: | + Delete filter chain associated to a specific route. + '/services/{service_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + delete: + summary: Delete Filter Chain Associated to a Specific Service + operationId: delete-services-service_id_or_name-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain associated to a specific service. + tags: + - filter-chains + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache +servers: + - description: Default Admin API URL + url: '{protocol}://{hostname}:{port}{path}' + variables: + hostname: + default: localhost + description: Hostname for Kong's Admin API + path: + default: / + description: Base path for Kong's Admin API + port: + default: '8001' + description: Port for Kong's Admin API + protocol: + default: http + description: Protocol for requests to Kong's Admin API + enum: + - http + - https +tags: + - description: | + Service entities are abstractions of your microservice interfaces or formal APIs. For example, a service could be a data transformation microservice or a billing API. +

+ The main attribute of a service is the destination URL for proxying traffic. This URL can be set as a single string or by specifying its protocol, host, port and path individually. +

+ Services are associated to routes, and a single service can have many routes associated with it. Routes are entrypoints in Kong Gateway which define rules to match client requests. Once a route is matched, Kong Gateway proxies the request to its associated service. See the [Proxy Reference](https://docs.konghq.com/gateway/latest/how-kong-works/routing-traffic/) for a detailed explanation of how Kong proxies traffic. +

+ Services can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). + name: Services + - description: | + Route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to the associated service. You need at least one matching rule that applies to the protocol being matched by the route. +

+ The combination of routes and services, and the separation of concerns between them, offers a powerful routing mechanism with which it is possible to define fine-grained entrypoints in Kong Gateway leading to different upstream services of your infrastructure. +

+ Depending on the protocol, one of the following attributes must be set: +
+ * `http`: At least one of `methods`, `hosts`, `headers`, or `paths` + * `https`: At least one of `methods`, `hosts`, `headers`, `paths`, or `snis` + * `tcp`: At least one of `sources` or `destinations` + * `tls`: at least one of `sources`, `destinations`, or `snis` + * `tls_passthrough`: set `snis` + * `grpc`: At least one of `hosts`, `headers`, or `paths` + * `grpcs`: At least one of `hosts`, `headers`, `paths`, or `snis` +
+ + A route can't have both `tls` and `tls_passthrough` protocols at same time. +

+ + Learn more about the router: + * [Configure routes using expressions](https://docs.konghq.com/gateway/latest/key-concepts/routes/expressions/) + * [Router Expressions language reference](https://docs.konghq.com/gateway/latest/reference/expressions-language/) + name: Routes + - description: | + A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. Plugins let you add functionality to services that run behind a Kong Gateway instance, like authentication or rate limiting. + You can find more information about available plugins and which values each plugin accepts at the [Plugin Hub](https://docs.konghq.com/hub/). +

+ When adding a plugin configuration to a service, the plugin will run on every request made by a client to that service. If a plugin needs to be tuned to different values for some specific consumers, you can do so by creating a separate plugin instance that specifies both the service and the consumer, through the service and consumer fields. +

+ Plugins can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). + name: Plugins + - description: | + The consumer object represents a consumer - or a user - of a service. + You can either rely on Kong Gateway as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong Gateway and your existing primary datastore. + name: Consumers + - description: | + A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong Gateway to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. +

+ Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. +

+ If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string. + name: Certificates + - description: | + An SNI object represents a many-to-one mapping of hostnames to a certificate. +

+ A certificate object can have many hostnames associated with it. When Kong Gateway receives an SSL request, it uses the SNI field in the Client Hello to look up the certificate object based on the SNI associated with the certificate. + name: SNIs + - description: | + A CA certificate object represents a trusted certificate authority. + These objects are used by Kong Gateway to verify the validity of a client or server certificate. + name: CA Certificates + - description: | + The upstream object represents a virtual hostname and can be used to load balance incoming requests over multiple services (targets). +

+ An upstream also includes a [health checker](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/), which can enable and disable targets based on their ability or inability to serve requests. + The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + name: Upstreams + - description: | + Vault objects are used to configure different vault connectors for [managing secrets](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/). + Configuring a vault lets you reference secrets from other entities. + This allows for a proper separation of secrets and configuration and prevents secret sprawl. +

+ For example, you could store a certificate and a key in a vault, then reference them from a certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure. +

+ Secrets rotation can be managed using [TTLs](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + name: Vaults + - description: | + A key object holds a representation of asymmetric keys in various formats. When Kong Gateway or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + name: Keys + - description: | + A JSON Web key set. Key sets are the preferred way to expose keys to plugins because they tell the plugin where to look for keys or have a scoping mechanism to restrict plugins to specific keys. + name: Key-sets + - description: Information routes + name: Information + - description: Debug routes + name: Debug + - description: | + A target is an IP address or hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. +

+ To disable a target, post a new one with `weight=0`, or use the `DELETE` method to accomplish the same. + name: Targets + - description: | + Tags are strings associated to entities in Kong Gateway. Tags can contain almost all UTF-8 characters, with the following exceptions: `,`,`/`, and non-printable ASCII (for example, the space character). +

+ Most core entities can be tagged via the tags attribute upon creation or modification. + name: Tags + - description: | + Retreieve information about the status of data planes when Kong Gateway is configured in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache diff --git a/api-specs/Gateway-OSS/3.9/kong-oss.yaml b/api-specs/Gateway-OSS/3.9/kong-oss.yaml new file mode 100644 index 000000000000..874abf7d52d8 --- /dev/null +++ b/api-specs/Gateway-OSS/3.9/kong-oss.yaml @@ -0,0 +1,8083 @@ +components: + parameters: + pagination-offset: + description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources + in: query + name: offset + schema: + type: string + pagination-size: + description: Number of resources to be returned. + in: query + name: size + schema: + default: 100 + maximum: 1000 + minimum: 1 + type: integer + pagination-tags-filter: + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using ','' to mean AND or using ''/'' to mean OR.' + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + service_id_or_name: + name: service_id_or_name + description: ID **or** name of the service to lookup + example: test-service + in: path + required: true + schema: + type: string + ca_certificate_id: + name: ca_certificate_id + description: ID of the related certificate + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + certificate_id: + name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier of the Certificate to retrieve. + certificate_name_or_id: + name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + sni_name_or_id: + name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + filter_chain_name_or_id: + name: filter_chain_name_or_id + in: path + required: true + schema: + type: string + example: my-filter-chain + description: The unique identifier or name of the Filter Chain to create or update. + plugin_id: + name: plugin_id + in: path + required: true + schema: + type: string + example: response-ratelimiting + description: The unique identifier of the Plugin to create or update. + key-set_id_or_name: + name: key-set_id_or_name + in: path + required: true + schema: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + description: The unique identifier or the `name` attribute of the Key Set that should be associated to the newly-created Key. + key_id_or_name: + name: key_id_or_name + in: path + required: true + schema: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725 + description: The unique identifier or the name of the Key to retrieve. + route_id_or_name: + name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + upstream_id_or_name: + name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + target_id_or_target: + name: target_id_or_target + in: path + required: true + schema: + type: string + example: 'example.com:8000' + description: The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. + vault_id_or_prefix: + name: vault_id_or_prefix + in: path + required: true + schema: + type: string + example: env + description: The unique identifier or the prefix of the Vault to retrieve. + tag: + name: tags + in: path + required: true + schema: + type: string + example: example + description: Tags are strings associated to entities in Kong. + log_level: + name: log_level + in: path + required: true + schema: + type: string + enum: + - info + - notice + - warn + - error + - crit + example: warn + description: Log levels are set in Kong's configuration. Log levels increase in order of their severity + filter_chain_id: + name: filter_chain_id + in: path + required: true + schema: + type: string + description: The unique identifier of the filter chain to retrieve. + schemas: + UnauthorizedError: + type: object + properties: + status: + type: integer + message: + type: string + required: + - status + - message + CA-Certificate: + description: A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate. CA Certificates can be both tagged and filtered by tags. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f260 + type: object + title: CA-Certificate + properties: + cert: + description: PEM-encoded public certificate of the CA. + type: string + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + description: SHA256 hex digest of the public certificate. + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f + format: uuid + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: '["user-level", "low-priority"]' + x-examples: + 200 - list of multiple certificates: + data: + - id: 43429efd-b3a5-4048-94cb-5cc4029909bb + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + - id: d26761d5-83a4-4f24-ac6c-cff276f2b79c + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + Certificate: + description: A certificate object represents a public certificate. These fields are _referenceable_, and can be stored as [secrets](http://docs.konqhq.com/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + type: object + title: Certificate + properties: + cert: + description: PEM-encoded public certificate chain of the SSL key This field is referenceable and can be stored in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + example: '"-----BEGIN CERTIFICATE-----\ncertificate-content\n-----END CERTIFICATE-----"' + cert_alt: + description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs. + type: string + example: '"-----BEGIN CERTIFICATE-----..."' + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + description: The UUID representation of the certificate object. + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + format: uuid + key: + description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + example: ' "-----BEGIN RSA PRIVATE KEY-----..."' + key_alt: + description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). + type: string + example: '"-----BEGIN EC PRIVATE KEY-----..."' + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: '["user-level", "low-priority"]' + snis: + description: > + A list of SNIs associated with the certificate. + type: array + items: + type: string + format: host + Consumer: + 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. + example: + custom_id: '4200' + id: 8a388226-80e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + 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 + id: + type: string + tags: + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + type: array + username: + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + type: string + type: object + title: Consumer + Filter-chain: + description: A Filter Chain entity represents a list of one or more WebAssembly filters that will be executed during the HTTP request/response lifecycle. + example: + id: "ce44eef5-41ed-47f6-baab-f725cecf98c7" + name: "my-filter-chain" + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: "20487393-41ed-47f6-93a8-3407cade2002" + filters: + - name: "go-rate-limiting" + enabled: true + config: '{ "minute": 30 }' + - name: "rust-response-transformer" + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: ["my-tag"] + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + description: Whether the filter chain is applied. + type: boolean + filters: + description: "An array of filter definitions that will be executed in order." + type: array + items: + type: object + properties: + name: + description: "The name of the filter. This name matches the basename of the WebAssembly module file: for a filter file called `my-filter.wasm`, then filter name will be `my-filter`." + type: string + config: + description: "The configuration for the filter. Proxy-Wasm does not define a configuration format, so this field accepts either a raw string, or a JSON object. A raw string is passed uninterpreted to the filter, to be validated at request time. If a JSON object is used, there must be a metadata file called `my-filter.meta.json` in the same folder as your `my-filter.wasm` file. The metadata file must contain an object with a field `\"config_schema\"`, and its value must the JSON Schema for the filter configuration. This schema will be used for validating the configuration upon insertion in the filter chain, ahead of execution." + oneOf: + - type: string + - type: object + enabled: + description: Whether the filter is to be applied. + type: boolean + id: + type: string + name: + description: The name of the filter chain. + type: string + route: + additionalProperties: false + description: "The route to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: "The service to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Filter Chain for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Filter Chain + Key: + description: A Key object holds a representation of asymmetric keys in various formats. When Kong or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + example: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + type: object + title: Key + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + description: The unique identifier or the prefix of the Vault to delete. + jwk: + description: A JSON Web Key represented as a string. + type: string + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + kid: + description: A unique identifier for a key. + type: string + example: '"42"' + name: + description: The name to associate with the given keys. + type: string + example: a-key + pem: + description: A keypair in PEM format. + type: object + properties: + private_key: + type: string + example: '"-----BEGIN"' + public_key: + type: string + example: '"-----BEGIN"' + set: + additionalProperties: false + description: The id (an UUID) of the key-set with which to associate the key. + type: object + properties: + id: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + tags: + description: An optional set of strings associated with the Key for grouping and filtering. + type: array + items: + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + example: 1422386534 + Key-set: + type: object + title: Key-set + description: A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + description: The unique identifier or the name of the Key to delete. + name: + type: string + description: The name to associate with the given key-set. + example: '"example-key-set"' + tags: + type: array + description: An optional set of strings associated with the Key for grouping and filtering + items: + type: string + example: '["google-keys", "mozilla-keys"]' + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + tags: + - idp-keys + Plugin: + description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. + example: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + properties: + config: + description: The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/). + type: object + consumer: + additionalProperties: false + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the plugin is applied. + type: boolean + id: + type: string + instance_name: + type: string + name: + description: The name of the Plugin thats going to be added. Currently, the Plugin must be installed in every Kong instance separately. + type: string + protocols: + default: + - grpc + - grpcs + - http + - https + description: A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `"tcp"` and `"tls"`. + items: + type: string + type: array + route: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. Leave unset for the plugin to activate regardless of the service being matched. + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Plugin + Route: + description: Route entities define rules to match client requests. Every request matching a given route will be proxied to its associated service. + example: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + type: object + title: Route + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + destinations: + description: A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + type: array + items: + type: object + properties: + '': {} + headers: + description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression. + type: object + hosts: + description: A list of domain names that match this route. Note that the hosts value is case sensitive. + type: array + items: + type: string + example: '"foo.example.com"' + https_redirect_status_code: + default: 426 + description: The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. This config applies only if the route is configured to only accept the `https` protocol. + type: integer + id: + type: string + example: 56c4566c-14cc-4132-9011-4139fcbbe50a + methods: + description: A list of HTTP methods that match this route. + type: array + items: + type: string + name: + description: The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test". + type: string + path_handling: + default: v0 + description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. + type: string + paths: + description: A list of paths that match this route. + type: array + items: + type: string + preserve_host: + default: false + description: When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the services `host`. + type: boolean + protocols: + default: + - http + - https + description: An array of the protocols this route should allow. See the [route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error. + type: array + items: + type: string + regex_priority: + default: 0 + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + type: integer + request_buffering: + default: true + description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. + type: boolean + response_buffering: + default: true + description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. + type: boolean + service: + additionalProperties: false + description: The service this route is associated to. This is where the route proxies traffic to. + type: object + properties: + id: + type: string + expression: + description: The route expression used for advanced routing scenarios. This field is used to evaluate route matches based on complex criteria beyond the standard routing fields. + type: string + priority: + description: A number used to specify the matching order for expression routes. The higher the `priority`, the sooner a route will be evaluated. This field is ignored unless `expression` field is set. The value must be between 0 and 2^46 - 1. + type: integer + default: 0 + snis: + description: A list of SNIs that match this route when using stream routing. + type: array + items: + type: string + sources: + description: A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + type: array + items: + type: object + properties: + '': {} + strip_path: + default: true + description: When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL. + type: boolean + tags: + description: An optional set of strings associated with the route for grouping and filtering. + type: array + items: + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + SNI: + description: An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate. + example: + certificate: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + id: 36c4566c-14cc-4132-9011-4139fcbbe50a + name: some.example.org + type: object + properties: + certificate: + additionalProperties: false + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: + description: The SNI name to associate with the given certificate. + type: string + example: my-sni + tags: + description: An optional set of strings associated with the SNIs for grouping and filtering. + type: array + items: + type: string + example: 'user-level, enterprise' + Service: + description: service entities are abstractions of upstream services. The main attribute of a service is its URL which can be set as a single string or by specifying the `protocol`, `host`, `port` and `path` individually. + example: + host: example.internal + id: 49fd316e-c457-481c-9fc7-8079153e4f3c + name: example-service + path: / + port: 80 + protocol: http + type: object + properties: + ca_certificates: + description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). + type: array + items: + type: string + client_certificate: + additionalProperties: false + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. + type: object + properties: + id: + type: string + connect_timeout: + default: 60000 + description: The timeout in milliseconds for establishing a connection to the upstream server. + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + enabled: + default: true + description: Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). + type: boolean + host: + description: The host of the upstream server. Note that the host value is case sensitive. + type: string + id: + type: string + name: + description: The service name. + type: string + path: + description: The path to be used in requests to the upstream server. + type: string + port: + default: 80 + description: The upstream server port. + type: integer + protocol: + default: http + description: The protocol used to communicate with the upstream. + type: string + read_timeout: + default: 60000 + description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. + type: integer + retries: + default: 5 + description: The number of retries to execute upon failure to proxy. + type: integer + tags: + description: An optional set of strings associated with the service for grouping and filtering. + type: array + items: + type: string + tls_verify: + description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected. + type: boolean + tls_verify_depth: + description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected.' + type: integer + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + url: + description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses. + type: string + write_timeout: + default: 60000 + description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. + type: integer + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + title: Service + Target: + description: A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. To disable a target, post a new one with `weight=0`; alternatively, use the `DELETE` convenience method to accomplish the same. The current target object definition is the one with the latest `created_at`. + example: + id: 089292a7-ba3d-4d88-acf0-97b4b2e2621a + target: 203.0.113.42 + upstream: + id: 5f1d7e76-2fed-4806-a6af-869984f025cb + weight: 100 + type: object + properties: + created_at: + description: Unix epoch when the resource was created. + type: number + example: 1422386534 + id: + type: string + example: 173a6cee-90d1-40a7-89cf-0329eca780a6 + description: The unique identifier or the name of the upstream for which to update the target. + tags: + description: An optional set of strings associated with the Target for grouping and filtering. + type: array + items: + type: string + target: + description: The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record. + type: string + upstream: + additionalProperties: false + type: object + description: The unique identifier or the name of the upstream for which to update the target. + properties: + id: + type: string + example: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + weight: + default: 100 + description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + example: 100 + x-examples: + Example 1: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + created_at: 1422386534 + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + Upstream: + description: The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a service object whose `host` is `service.v1.xyz`. Requests for this service would be proxied to the targets defined within the upstream. An upstream also includes a health check, which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + example: + algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + properties: + algorithm: + default: round-robin + description: Which load balancing algorithm to use. + type: string + client_certificate: + additionalProperties: false + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + hash_fallback: + default: none + description: What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`. + type: string + hash_fallback_header: + description: The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. + type: string + hash_fallback_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + type: string + hash_fallback_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + type: string + hash_on: + default: none + description: What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. + type: string + hash_on_cookie: + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + type: string + hash_on_cookie_path: + default: / + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + type: string + hash_on_header: + description: The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. + type: string + hash_on_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + type: string + hash_on_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + type: string + healthchecks: + properties: + active: + properties: + concurrency: + default: 10 + type: integer + headers: + type: object + healthy: + properties: + http_statuses: + default: + - 200 + - 302 + items: + type: integer + type: array + interval: + default: 0 + type: number + successes: + default: 0 + type: integer + type: object + http_path: + default: / + type: string + https_sni: + type: string + https_verify_certificate: + default: true + type: boolean + timeout: + default: 1 + type: number + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + items: + type: integer + type: array + interval: + default: 0 + type: number + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + passive: + properties: + healthy: + properties: + http_statuses: + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + items: + type: integer + type: array + successes: + default: 0 + type: integer + type: object + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 500 + - 503 + items: + type: integer + type: array + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + threshold: + default: 0 + type: number + type: object + host_header: + description: The hostname to be used as `Host` header when proxying requests through Kong. + type: string + id: + type: string + name: + description: This is a hostname, which must be equal to the `host` of a service. + type: string + slots: + default: 10000 + description: The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`. + type: integer + tags: + description: An optional set of strings associated with the Upstream for grouping and filtering. + items: + type: string + type: array + use_srv_name: + default: false + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`. + type: boolean + type: object + Vault: + description: Vault entities are used to configure different Vault connectors. Examples of Vaults are Environment Variables, HashiCorp Vault and AWS Secrets Manager. Configuring a Vault allows referencing the secrets with other entities. For example a certificate entity can store a reference to a certificate and key, stored in a vault, instead of storing the certificate and key within the entity. This allows a proper separation of secrets and configuration and prevents secret sprawl. + example: + config: + prefix: vaults.config.resurrect_ttl + description: environment variable based vault + id: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + name: env + tags: + - foo + - bar + properties: + config: + description: The configuration properties for the Vault which can be found on the [vaults' documentation page](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + type: object + properties: + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + enum: + - vaults.config.resurrect_ttl + - vaults.config.neg_ttl + - vaults.config.ttl + required: + - prefix + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + description: + description: The description of the Vault entity. + type: string + example: This vault is used to retrieve redis database access credentials + id: + type: string + example: B2A30E8F-C542-49CF-8015-FB674987D1A5 + name: + description: The name of the Vault thats going to be added. Currently, the Vault implementation must be installed in every Kong instance. + type: string + example: env + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + example: env + tags: + description: An optional set of strings associated with the Vault for grouping and filtering. + type: array + items: + type: string + example: database-credentials + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + example: 1422386534 + x-examples: + Example Vault: + id: B2A30E8F-C542-49CF-8015-FB674987D1A5 + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + created_at: 1422386534 + updated_at: 1422386534 + tags: + - database-credentials + - data-plane + Filter-chains: + type: object + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: my-chain + created_at: 1422386534 + updated_at: 1422386534 + enabled: true + route: null + service: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + - name: go-rate-limiting + enabled: true + config: '{ "minute": 30 }' + - name: rust-response-transformer + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: + - my-tag + description: A filter chain is the database entity representing one or more WebAssembly filters executed for each request to a particular service or route, each one with its configuration. + title: Filter Chains + properties: + id: + type: string + description: The unique identifier or the name attribute of the route that should be associated to the newly created filter chain. + example: ce44eef5-41ed-47f6-baab-f725cecf98c7 + format: uuid + name: + type: string + description: | + The name of the filter chain. + example: my-chain + created_at: + type: integer + example: 1422386534 + updated_at: + type: integer + example: 1422386534 + enabled: + type: boolean + description: | + Whether the filter chain is applied. Default: true. + default: true + route: + description: The route to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `route.id=` or `route.name=`. In JSON format, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: The service to which this chain is applied. A filter chain must be applied to either a single route or a single service. Default `null`. In form-encoded format, the notation is `service.id=` or `service.name=`. In JSON format, use `"service":{"id":""}` or `"service":{"name":""}`. + example: 20487393-41ed-47f6-93a8-3407cade2002 + filters: + type: array + description: An array of filter definitions. Each filter is an object containing a mandatory name, an optional config, and a boolean enabled setting. + items: + type: object + properties: + name: + type: string + description: | + The name of the filter + example: go-rate-limiting + enabled: + type: boolean + description: Enable the filter + config: + type: string + description: configuration filter headers + example: '{ \"minute\": 30 }' + tags: + type: array + items: + type: string + pagination-offset-response: + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + type: string + requestBodies: + CA-cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: | + PEM-encoded public certificate of the CA. + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + description: | + SHA256 hex digest of the public certificate. + tags: + type: array + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + required: + - cert + description: This request body represents a new Certificate Authority (CA) certificate and includes the properties required to create a new certificate. + cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example: + id: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + key: '-----BEGIN RSA PRIVATE KEY-----...' + cert_alt: '-----BEGIN CERTIFICATE-----...' + key_alt: '-----BEGIN EC PRIVATE KEY-----...' + snis: + - foo.test + - example.com + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: PEM-encoded public certificate chain of the SSL key pair. + example: '"-----BEGIN CERTIFICATE-----...",' + key: + type: string + example: '"-----BEGIN RSA PRIVATE KEY-----..."' + description: PEM-encoded private key of the SSL key pair. + cert_alt: + type: string + description: PEM-encoded public certificate chain of the alternate SSL key pair. + key_alt: + type: string + description: PEM-encoded private key of the alternate SSL key pair. + example: '"-----BEGIN EC PRIVATE KEY-----..."' + snis: + type: array + description: An array of zero or more hostnames to associate with this certificate as SNIs. + items: + type: string + tags: + type: array + description: | + An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + passphrase: + type: string + description: To load an encrypted private key into Kong, specify the passphrase using this attributKong will decrypt the private key and store it in its database. e. Enterprise Only + example: example + required: + - cert + - key + create-sni: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-sni + tags: + - user-level + - low-priority + certificate: + id: a2e013e8-7623-4494-a347-6d29108ff68b + properties: + name: + type: string + description: The SNI name to associate with the given certificate. + example: my-sni + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + example: '["user-level", "low-priority"]' + certificate: + type: object + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is `certificate.id=`. With JSON, use `"certificate":{"id":""}`. + properties: + id: + type: string + example: 91020192-062d-416f-a275-9addeeaffaf2 + description: 91020192-062d-416f-a275-9addeeaffaf2 + required: + - name + - certificate + description: A JSON object containing the details of the new SNI, including the name, certificate, and tags. + consumer-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + username: + type: string + description: | + The unique username of the Consumer. You must send either this field or custom_id with the request. + custom_id: + type: string + 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. + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + required: + - username + - custom_id + description: Consumer request body + filter-chains-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: "ce44eef5-41ed-47f6-baab-f725cecf98c7" + name: "my-filter-chain" + enabled: true + route: null + service: "20487393-41ed-47f6-93a8-3407cade2002" + filters: + - name: "go-rate-limiting" + enabled: true + config: '{ "minute": 30 }' + - name: "rust-response-transformer" + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: ["my-tag"] + properties: + enabled: + description: Whether the filter chain is applied. + type: boolean + example: true + filters: + description: "An array of filter definitions that will be executed in order." + type: array + items: + type: object + properties: + name: + description: "The name of the filter. This name matches the basename of the WebAssembly module file: for a filter file called `my-filter.wasm`, then filter name will be `my-filter`." + type: string + config: + description: "The configuration for the filter. Proxy-Wasm does not define a configuration format, so this field is a raw string, intended to contain the configuration in the format expected by the particular filter in use." + type: string + enabled: + description: Whether the filter is to be applied. + type: boolean + id: + type: string + name: + description: The name of the filter chain. + type: string + example: "my-filter-chain" + route: + additionalProperties: false + description: "The route to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: "The service to which this chain is applied. A filter chain must be applied to either a single route or a single service." + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Filter Chain for grouping and filtering. + items: + type: string + type: array + examples: + request example: + value: + id: "ce44eef5-41ed-47f6-baab-f725cecf98c7" + name: "my-filter-chain" + enabled: true + route: null + service: "20487393-41ed-47f6-93a8-3407cade2002" + filters: + - name: "go-rate-limiting" + enabled: true + config: '{ "minute": 30 }' + - name: "rust-response-transformer" + enabled: true + config: '{ "remove_header": "X-Example" }' + tags: ["my-tag"] + description: Filter Chain request body + plugin-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: rate-limiting + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + properties: + name: + type: string + description: | + The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately. + example: rate-limiting + route: + type: string + description: | + If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default: `null`. With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: | + If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: | + If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique globally for Kong Gateway OSS. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the Plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + examples: + request example: + value: + name: rate-limiting + route: string + service: string + consumer: string + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 500 + protocols: + - http + enabled: true + tags: + - string + description: Plugin request body + key-set-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-key_set + tags: + - google-keys + - mozilla-keys + properties: + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + keys-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + properties: + set: + type: object + description: The id (an UUID) of the key-set with which to associate the key .With form-encoded, the notation is `set.id=` or `set.name=`. With JSON, use `"set":{"id":""}` or `"set":{"name":""}.` + properties: + id: + type: string + description: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: + type: string + example: my-key + description: | + The name to associate with the given keys. + kid: + type: string + description: | + A unique identifier for a key. + example: '42' + jwk: + type: string + description: A JSON Web Key represented as a string. + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + pem: + type: object + description: | + A keypair in PEM format. + properties: + private_key: + type: string + example: 'private_key": "-----BEGIN' + public_key: + type: string + example: 'public_key": "-----BEGIN' + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + required: + - kid + route-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + snis: + - foo.test + - example.com + sources: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + destinations: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + properties: + name: + type: string + description: | + The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test". + protocols: + type: array + description: An array of the protocols this route should allow + items: + type: string + default: https + example: tcp + methods: + type: array + description: | + A list of HTTP methods that match this route. + items: + type: string + example: GET + hosts: + type: array + description: A list of domain names that match this route. Note that the hosts value is case sensitive. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array. + items: + type: string + paths: + type: array + description: A list of paths that match this route. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an array. The path can be a regular expression, or a plain text pattern. + items: + type: string + headers: + type: object + description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The Host header cannot be used with this hosts should be specified using the `hosts` attribute. When headers contains only one value and that value starts with the special prefix` ~*`, the value is interpreted as a regular expression. + properties: + x-my-header: + type: array + items: + type: string + x-another-header: + type: array + items: + type: string + https_redirect_status_code: + type: integer + description: |- + The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS` + Location header is injected by Kong if the field is set to `301`, `302`, `307` or `308`. Note: This config applies only if the route is configured to only accept the https protocol. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`. + default: 426 + enum: + - 426 + - 301 + - 302 + - 307 + - 308 + example: 426 + regex_priority: + type: integer + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). + default: 0 + example: 0 + strip_path: + type: boolean + description: When matching a route via one of the paths, strip the matching prefix from the upstream request URL. + default: true + path_handling: + type: string + description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. Accepted values are "`v0`", "`v1`". + enum: + - v1 + - v0 + example: v0 + preserve_host: + type: boolean + description: | + When matching a route via one of the `hosts` domain names, use the request `host` header in the upstream request headers. If set to `false`, the upstream Host header will be that of the service's host. + default: true + request_buffering: + type: boolean + default: true + description: | + Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true. + response_buffering: + type: boolean + default: true + description: | + Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: `true`. + snis: + type: array + description: | + A list of SNIs that match this route when using stream routing. + items: + type: string + sources: + type: array + description: | + A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 10.1.0.0/16 + port: + type: integer + example: 1234 + destinations: + type: array + description: | + A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + items: + type: object + properties: + ip: + type: string + example: 0.1.0.0/16 + port: + type: integer + tags: + type: array + description: | + An optional set of strings associated with the route for grouping and filtering. + items: + type: string + service: + type: object + description: The service this route is associated to. This is where the route proxies traffic to. With form-encoded, the notation is service.id= or service.name=. With JSON, use `"service":{"id":""}` or `"service":{"name":""}`. + properties: + id: + type: string + example: af8330d3-dbdc-48bd-b1be-55b98608834b + required: + - protocols + - https_redirect_status_code + - preserve_host + - request_buffering + - response_buffering + examples: + Create a route: + value: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + description: Route request body + service-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + properties: + name: + type: string + description: | + The service name. + example: my-service + retries: + type: integer + description: | + The number of retries to execute upon failure to proxy. Default:`5`. + default: 5 + example: 5 + protocol: + type: string + description: |- + The protocol used to communicate with the upstream. Accepted values are: "`grpc`", "`grpcs`", "`http`", "`https`", "`tcp`", "`tls`", "`tls_passthrough`", "`udp`", "`ws`" + , "`wss`" + . Default: "`http`". + default: http + enum: + - grpc + - grpcs + - http + - https + - tcp + - 'tls ' + - tls_passthrough + - udp + - ws + - wss + example: http + host: + type: string + description: | + The host of the upstream server. Note that the host value is case sensitive. + example: example.com + port: + type: integer + description: | + The upstream server port. Default: `80`. + default: 80 + example: 80 + path: + type: string + description: | + The path to be used in requests to the upstream server. + example: /some_api + connect_timeout: + type: integer + description: The timeout in milliseconds for establishing a connection to the upstream server. + default: 6000 + example: 6000 + write_timeout: + type: integer + description: | + The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + read_timeout: + type: integer + description: | + The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + tags: + type: array + description: | + An optional set of strings associated with the service for grouping and filtering. + items: + type: string + example: user-level + client_certificate: + type: object + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is `client_certificate.id=`. With JSON, use `"client_certificate":{"id":""}`. + properties: + id: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: + type: boolean + description: | + Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected. + default: true + tls_verify_depth: + type: string + description: | + Maximum depth of chain while verifying Upstream server's TLS certificate. If set to null, then the Nginx default is respected. Default: null. + example: respected + default: null + nullable: true + ca_certificates: + type: array + description: | + Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to null when Nginx default is respected. + With form-encoded, the notation is `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`. With JSON, use an Array. + items: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: + type: boolean + default: true + description: | + Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`. + required: + - protocol + - host + - port + - enabled + examples: + Example: + value: + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 6000 + write_timeout: 6000 + read_timeout: 6000 + tags: + - user-level + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: true + upstream-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + - x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + properties: + name: + type: string + description: This is a hostname, which must be equal to the `host` of a service. + example: my-upstream + algorithm: + type: string + description: | + Which load balancing algorithm to use. Accepted values are: `"consistent-hashing"`, `"least-connections"`,` "round-robin"`. Default: `"round-robin"`. + enum: + - consistent-hashing + - least-connections + - round-robin + - latency + default: round-robin + example: round-robin + hash_on: + type: string + description: What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + hash_fallback: + type: string + description: What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no Consumer identified). Not available if hash_on is set to cookie. + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + example: none + hash_on_header: + type: string + description: The header name to take the value from as hash input. Only required when `hash_on` is set to header. + example: none + hash_fallback_header: + type: string + description: The header name to take the value from as hash input. Only required when hash_fallback is set to header. + default: none + example: none + hash_on_cookie: + type: string + description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + example: none + hash_on_cookie_path: + type: string + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + default: / + example: / + hash_on_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + example: hash_value + hash_fallback_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + example: hash_value + hash_on_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + example: hash_value + hash_fallback_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + example: hash_value + slots: + type: integer + description: The number of slots in the load balancer algorithm. If the algorithm is set to `round-robin`, this setting determines the maximum number of slots. If the algorithm is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range 10-65536. + minimum: 10 + maximum: 65536 + default: 10000 + example: 5000 + healthchecks: + type: object + properties: + passive: + type: object + properties: + type: + type: string + description: Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, http and https options are equivalent. Accepted values are `tcp`, `http`, `https`, `grpc`, `grpcs`. + default: http + enum: + - tcp + - http + - https + - grpc + - grpcs + example: tcp + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=201`. With JSON, use an array. + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + example: + - 200 + - 201 + - 202 + items: + type: integer + enum: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: + type: integer + description: Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks. + default: 0 + example: 2 + unhealthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an array. + default: + - 429 + - 500 + - 503 + example: + - 500 + - 503 + items: + type: integer + enum: + - 429 + - 500 + - 503 + timeouts: + type: integer + description: Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + http_failures: + type: integer + description: Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 3 + tcp_failures: + type: integer + description: Number of TCP connection failures to consider a target unhealthy, as observed by passive health checks. + default: 0 + example: 1 + active: + type: object + properties: + https_verify_certificate: + type: boolean + healthy: + type: object + properties: + http_statuses: + type: array + description: An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an array. + default: + - 200 + - 302 + example: + - 200 + - 201 + items: + type: integer + successes: + type: integer + description: Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. + default: 0 + example: 3 + interval: + type: integer + description: Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. + default: 0 + example: 30 + unhealthy: + type: object + properties: + http_failures: + type: integer + description: Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. + default: 0 + example: 2 + http_statuses: + type: array + description: An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=404`. With JSON, use an array. + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + example: + - 400 + - 404 + items: + type: integer + timeouts: + type: integer + description: Number of timeouts in active probes to consider a target unhealthy. + default: 0 + example: 2 + tcp_failures: + type: integer + description: Number of TCP failures in active probes to consider a target unhealthy. + default: 0 + example: 1 + interval: + type: integer + description: Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. + default: 0 + example: 10 + type: + type: string + description: Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. + enum: + - tcp + - http + - https + - grpc + - grpcs + default: http + example: https + concurrency: + type: integer + description: Number of targets to check concurrently in active health checks. + default: 10 + example: 5 + headers: + type: object + description: One or more lists of values indexed by header name to use in GET HTTP request to run as a probe on active health checks. Values must be pre-formatted. + example: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: + type: integer + description: Socket timeout for active health checks (in seconds). + default: 1 + example: 5 + http_path: + type: string + description: Path to use in GET HTTP request to run as a probe on active health checks. + default: / + https_sni: + type: string + description: + The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. + This is particularly useful when Targets are configured using IPs, so that the target host's certificate can be verified with the proper SNI. + threshold: + type: integer + description: The minimum percentage of the upstream's targets' weight that must be available for the whole upstream to be considered healthy. + minimum: 0 + maximum: 100 + default: 0 + tags: + type: array + description: An optional set of strings associated with the Upstream for grouping and filtering. + example: + - user-level + - low-priority + items: + type: string + host_header: + type: string + description: The hostname to be used as Host header when proxying requests through Kong. + client_certificate: + type: object + description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. + properties: + id: + type: string + example: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: + type: boolean + description: If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host. + example: false + required: + - name + examples: + Upstream: + value: + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + Example request: + value: + name: my-upstream + tags: + - user-level + - low-priority + algorithm: round-robin + target-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + properties: + target: + default: example.com:8000 + description: The target for the upstream + type: string + weight: + default: 100 + description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. + type: integer + minimum: 0 + maximum: 65535 + tags: + type: array + description: An optional set of strings associated with the Target for grouping and filtering. + items: + type: string + examples: + Example: + value: + target: example.com:8000 + weight: 100 + tags: + - string + vault-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + properties: + prefix: + type: string + description: | + The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + example: env + name: + type: string + description: | + The name of the Vault that's going to be added. Currently, the Vault implementation must be installed in every Kong instance. + example: env + description: + type: string + description: | + The description of the Vault object. + example: This vault is used to retrieve redis database access credentials + config: + type: object + description: | + The configuration properties for the Vault which can be found on the vaults' documentation page. + properties: + prefix: + type: string + example: SSL_ + tags: + type: array + description: | + An optional set of strings associated with the Vault for grouping and filtering. + items: + type: string + examples: + Example 1: + value: + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + responses: + HTTP401Error: + content: + application/json: + examples: + DuplicateApiKey: + summary: Duplicate API key found + value: + message: Duplicate API key found + status: 401 + InvalidAuthCred: + summary: Invalid authentication credentials + value: + message: Unauthorized + status: 401 + NoAPIKey: + summary: No API key found + value: + message: No API key found in request + status: 401 + schema: + $ref: '#/components/schemas/UnauthorizedError' + description: Unauthorized + get-endpoints: + description: Example response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: string + x-examples: + Example 1: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - '/schemas/filters/{name}' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + examples: + Get all endpoints: + value: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{certificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /debug/profiling/memory + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /filter-chains + - '/filter-chains/{filter_chains}' + - '/filter-chains/{filter_chains}/route' + - '/filter-chains/{filter_chains}/service' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/filter-chains' + - '/routes/{routes}/filter-chains/{filter_chains}' + - '/routes/{routes}/filters/all' + - '/routes/{routes}/filters/disabled' + - '/routes/{routes}/filters/enabled' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/filter-chains' + - '/services/{services}/filter-chains/{filter_chains}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + sni-response: + description: SNI response object + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + name: my-sni + created_at: 1422386534 + tags: + - user-level + - low-priority + certificate: + id: a3ad71a8-6685-4b03-a101-980a953544f6 + - id: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: my-sni + created_at: 1422386534 + tags: + - admin + - high-priority + - critical + certificate: + id: 4e8d95d4-40f2-4818-adcb-30e00c349618 + next: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + description: Array of SNIs + items: + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + description: The unique identifier or the name attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + name: + type: string + description: | + The SNI name to associate with the given certificate. + example: my-sni + created_at: + type: integer + example: 1422386534 + description: | + Unix epoch when the resource was created. + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + certificate: + type: object + description: | + The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + properties: + id: + type: string + example: 2e013e8-7623-4494-a347-6d29108ff68b + description: The unique identifier or the name attribute of the Certificate whose SNIs + next: + type: string + example: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + consumer-response-data: + description: The consumer object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + - id: 01c23299-839c-49a5-a6d5-8864c09184af + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier or the name attribute of the consumer. + example: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1422386534 + username: + type: string + description: The unique username of the consumer. You must send either this field or` custom_i`d with the request. + example: my-username + custom_id: + type: string + description: Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. + example: my-custom-id + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + example: admin + next: + type: string + description: Pagination information + example: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + consumer-create-response: + description: New consumer created response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + id: + type: string + description: The unique id of the consumer. + example: c1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: + type: integer + description: | + Unix epoch when the resource was created. + username: + type: string + description: The unique username of the consumer. + custom_id: + type: string + description: Field for the unique consumer ID + tags: + type: array + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + plugin-response: + description: Example response + content: + application/json: + schema: + type: object + properties: + id: + type: string + name: + type: string + description: | + The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately. + example: rate-limiting + created_at: + type: integer + description: Unix epoch when the resource was created. + route: + type: string + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`. + nullable: true + service: + type: string + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. + nullable: true + consumer: + type: string + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.) + nullable: true + instance_name: + type: string + description: | + An optional custom name to identify an instance of the plugin, for example `basic-auth_example-service`. + + The instance name shows up in Kong Manager, so it's useful when running the same + plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance + via the Kong Admin API. + + An instance name must be unique globally for Kong Gateway OSS. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the Plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + examples: + Plugin response: + value: + data: + - id: 02621eee-8309-4bf6-b36b-a82017a5393e + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + - id: 66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - tcp + - tls + enabled: true + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + key-set-response: + description: Key set object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - idp-keys + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + id: + type: string + example: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + created_at: + type: integer + description: Unix epoch when the resource was last created. + example: 1422386534 + updated_at: + type: integer + description: | + Unix epoch when the resource was last updated. + example: 1422386534 + tags: + type: array + description: | + The name to associate with the given key-set. + items: + type: string + next: + type: string + description: | + Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + example: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + examples: + example: + value: + id: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: my-key_set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - string + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + tags-response: + description: Tags response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - entity_name: services + entity_id: acf60b10-125c-4c1a-bffe-6ed55daefba4 + tag: s1 + offset: c47139f3-d780-483d-8a97-17e9adc5a7ab + next: /tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab + properties: + data: + type: array + items: + type: object + properties: + entity_name: + type: string + example: services + description: The name of the entity that corresponds to a tag + entity_id: + type: string + example: c87440e1-0496-420b-b06f-dac59544bb6c + description: The unique ID for the entity that is attached to the tag + tag: + type: string + example: example + description: The tag + offset: + type: string + example: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + next: + type: string + example: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + examples: + Tags response: + value: + data: + - entity_name: services + entity_id: c87440e1-0496-420b-b06f-dac59544bb6c + tag: example + offset: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + next: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 +externalDocs: + description: Kong Gateway Admin API (OSS) + url: 'https://docs.konghq.com' +info: + contact: + email: docs@konghq.com + name: Kong Inc + url: 'https://konghq.com' + description: |- + OpenAPI 3.0 spec for Kong Gateway's open source Admin API. + + You can know more about Kong Gateway at [docs.konghq.com](https://docs.konghq.com) + .Give Kong a star at [Kong/kong](https://github.com/kong/kong) repository. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + title: Kong Admin API + version: 3.8.0 +openapi: 3.0.0 +paths: + /: + get: + summary: Get Kong's instance information + tags: + - Information + operationId: geInfo + description: | + Returns detailed information about the Kong gateway instance, including the full Kong configuration, available and unavailable plugins, version, edition (enterprise or community), a tagline, the unique node identifier, and other metadata. + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + version: + type: string + description: The version number of the Kong instance. + example: "2.3.3" + edition: + type: string + description: Indicates whether the Kong instance is the Community or Enterprise edition. + example: "Community" + tagline: + type: string + description: A tagline or slogan for the Kong instance. + example: "Welcome to Kong" + node_id: + type: string + description: A unique identifier for the node, in UUID format. + format: uuid + example: "a74d7c4f-ef83-4bbe-a5e7-3f5409f4a0b9" + hostname: + type: string + description: The hostname of the Kong node. + example: "kong-node.example.com" + timers: + type: object + description: Information about running and pending timers. + properties: + running: + type: integer + description: The number of running timers. + example: 5 + pending: + type: integer + description: The number of pending timers. + example: 2 + plugins: + type: object + description: Information about plugins. + properties: + available_on_server: + type: object + additionalProperties: + type: object + properties: + version: + type: string + description: The version of the plugin. + priority: + type: integer + description: The priority of the plugin. + enabled_in_cluster: + type: array + items: + type: string + description: A list of distinct plugin names enabled in the cluster. + example: ["jwt", "acl"] + lua_version: + type: string + description: The version of Lua used by the Kong instance. + example: "LuaJIT 2.1.0-beta3" + configuration: + type: object + description: A sanitized version of the Kong configuration, excluding sensitive values. + additionalProperties: true + pids: + type: object + description: Process IDs for the master process and worker processes. + properties: + master: + type: integer + description: The PID of the master process. + example: 4321 + workers: + type: array + items: + type: integer + description: An array of worker process PIDs. + example: [1234, 5678] + examples: + openSourceExample: + summary: Open Source Edition Example Response + value: + configuration: + _debug_pg_ttl_cleanup_interval: 300 + admin_acc_logs: "/usr/local/kong/logs/admin_access.log" + admin_access_log: "/dev/stdout" + edition: "community" + hostname: "b8f553cfbd0c" + lua_version: "LuaJIT 2.1.0-20230410" + node_id: "39bfa49d-3394-4f8e-b9db-94b786bc4e5f" + pids: + master: 1 + workers: [1278, 1279, 1280, 1281, 1282, 1283, 1284, 1285] + plugins: + available_on_server: + acl: + priority: 950 + version: "3.6.0" + enabled_in_cluster: [] + tagline: "Welcome to kong" + timers: + pending: 1 + running: 145 + version: "3.6.0" + '401': + $ref: '#/components/responses/HTTP401Error' + '405': + description: Method Not Allowed + content: + application/json: + schema: + $ref: '#/components/schemas/UnauthorizedError' + headers: + Server: + description: Kong's server tokens. + schema: + type: string + example: "kong/2.3.3" + /ca_certificates: + get: + description: Retrieve a list of all available Certificate Authority (CA) certificates, including the certificate ID, creation date, and other details. You can use query parameters to filter the results by size or tags, for example `/ca-certificates?size=50&tags=enterprise`. + operationId: list-ca_certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + examples: {} + text/plain: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: A successful response listing CA Certificates + summary: List all CA certificates + tags: + - CA Certificates + post: + description: Create a new Certificate Authority (CA) certificate. The request body must include the `cert` property, the certificate data in PEM format; it can also include `cert_digest`, a digest of the certificate in hex format for verifying the certificates integrity, and `tags`, an optional list of tags to categorize the certificate. + operationId: create-ca_certificate + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: The created certificate object. + '400': + description: Invalid CA certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new CA certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + '/ca_certificates/{ca_certificate_id}': + delete: + description: Delete the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. + operationId: delete-ca_certificate + responses: + '204': + description: Successfully deleted CA Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a CA Certificate + tags: + - CA Certificates + get: + description: Retrieve details about the specified Certificate Authority (CA) certificate using the provided path parameter `ca_certificate_id`. + operationId: get-ca_certificate + parameters: + - description: The unique identifier of the certificate to retrieve. + in: path + name: ca_certificate_id + required: true + schema: + type: string + examples: + example: + summary: Example CA certificate ID + value: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: The specified CA certificate exists in the system, and the response includes details about the certificate. + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a CA certificate + tags: + - CA Certificates + patch: + description: |- + Update the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. Use this endpoint to modify an existing CA certificate in the system. The request body should include the fields of the CA certificate that need to be updated. + + > This API is not available in DB-less mode. + operationId: update-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully updated CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + put: + description: Create or Update a CA Certificate using the provided path parameter `ca_certificate_id`. + operationId: updatet-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully upserted CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + parameters: + - $ref: '#/components/parameters/ca_certificate_id' + /certificates: + get: + description: Retrieve a list of all available CA Certificate Authority (CA) certificates. You can use query parameters to filter the results by size or tags, for example `/certificates?size=50&tags=enterprise`. + operationId: list-certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Certificate' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Certificates + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all certificates + tags: + - Certificates + post: + description: |- + Create a new certificate with the provided details. Use this endpoint to add a new certificate to the system. The request body must include the certificate data and other details required for creating a new certificate. + + > Note: This API is not available in DB-less mode. + operationId: create-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + '/certificates/{certificate_id}': + delete: + description: | + Delete a Certificate + + >Note: This API is not available in DB-less mode. + operationId: delete-certificate + parameters: + - description: ID of the Certificate to delete + in: path + name: certificate_id + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Certificate + tags: + - Certificates + get: + description: Retrieve details about the specified certificate using the provided path parameter `certificate_id`. + operationId: get-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: HTTP 200 OK + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Certificate + tags: + - Certificates + patch: + description: |- + Update a Certificate + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + + >Note: This API is not available in DB-less mode. + operationId: update-certificate + parameters: + - description: ID of the Certificate to update + in: path + name: certificate_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + put: + description: | + Update details about the specified certificate using the provided path parameter `certificate_id`. + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + + + + > Note: This API is not available in DB-less mode. + operationId: update-certificate-put + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/certificate_id' + '/certificates/{certificate_name_or_id}/snis': + get: + description: Retrieve a paginated list of all SNIs associated with a certificate. Use this endpoint to retrieve a list of SNIs that are linked to a specific certificate. You can use the optional query parameters to filter the results based on specific criteria. The response will include the list of SNIs and pagination information. See the response schema for details on the expected format of the response body. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List SNIs associated with a certificate + tags: + - SNIs + operationId: get-sni-with-certificate + post: + description: Create a new SNI and associate it with a certificate in the system. Use this endpoint to add a new SNI to the system and link it to a specific certificate. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully created SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI associated with a Certificate + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: create-sni-for-certificate + parameters: + - $ref: '#/components/parameters/certificate_name_or_id' + '/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: | + Delete a an SNI associated with a Certificate using ID or name. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a an SNI associated with a Certificate + tags: + - SNIs + operationId: delete-sni-for-certificate + get: + description: Get an SNI associated with a Certificate using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully fetched SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI associated with a certificate + tags: + - SNIs + operationId: fetch-sni-with-certificate + patch: + description: |2 + + + + Update an existing SNI associated with a certificate in the system using the SNI ID or name. The request body should include the fields of the SNI that need to be updated, such as the name, description, or other properties. If the request body contains valid data, the endpoint will update the SNI and return a success response. + + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully updated SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update SNI associated to a certificate + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: update-sni-for-certificate + put: + description: | + Create or Update an SNI associated with a Certificate using ID or name. + + Inserts (or replaces) the SNI under the requested resource with the definition specified in the body. The SNI will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the SNI being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new SNI without specifying id (neither in the URL nor in the body), then it will be auto-generated. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully upserted SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert an SNI associated with a certificate + tags: + - SNIs + operationId: upsert-sni-for-certificate + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier of the Certificate to retrieve. + - name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + /consumers: + get: + description: Retrieve a list of all consumers.You can use query parameters to filter the results by size or tags, for example `/consumers?size=50&tags=enterprise`. + operationId: list-consumer + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Consumer' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Consumers + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Consumers + tags: + - Consumers + post: + description: Create a new Consumer + operationId: create-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully created Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + '/consumers/{consumer_username_or_id}': + delete: + description: Delete a specific consumer from the system using either the consumer ID or the consumer username. This operation is irreversible and permanently removes all data associated with the specified consumer. If the consumer was deleted succesfully the endpoint will return a 204 response indicating that the resource did not exist. + operationId: delete-consumer + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Consumer + tags: + - Consumers + get: + description: Retrieve the details of a specific consumer in the system using either the consumer ID or the consumer username. If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: get-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully fetched Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Consumer + tags: + - Consumers + patch: + description: Update the details of a specific consumer in the system using either the consumer ID or the consumer username.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + operationId: update-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully updated Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: |- + Create or Update Consumer using ID or username. The consumer will be identified via the username or id attribute.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + + When the username or id attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its id. Otherwise it will be identified by its username. + + When creating a new Consumer without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a username in the URL and a different one in the request body is not allowed. + + > Note: This API is not available in DB-less mode. + operationId: upsert-consumer + responses: + '200': + $ref: '#/components/responses/consumer-response-data' + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Not Found + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + '/consumers/{consumer_username_or_id}/plugins': + get: + description: Retrieve a list of all plugins associated with a consumer. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: List all plugins associated with a consumer + tags: + - Plugins + operationId: list-plugins-for-consumer + post: + description: Create a new Plugin associated with a Consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-consumer + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_username_or_id}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a Consumer using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Plugin associated with a Consumer + tags: + - Plugins + operationId: delete-plugin-for-consumer + get: + description: Get a Plugin associated with a Consumer using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a Consumer + tags: + - Plugins + operationId: fetch-plugin-for-consumer + patch: + description: Update a Plugin associated with a consumer using the consumer username or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-consumer + put: + description: Create or Update a Plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-consumer + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + - $ref: '#/components/parameters/plugin_id' + /key-sets: + get: + description: | + Retrieve a list of all Key-sets in the system. A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. Key Sets can be both tagged and filtered by tags. + operationId: list-key-set + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Key-sets + tags: + - Key-sets + post: + description: This endpoint allows creating a new Key-set by sending a JSON object that describes the Key-set to be created.The request body must contain all the fields required to create a new Key-set. + operationId: create-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + description: Returned if the request contains invalid data. + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + '/key-sets/{key-set_id_or_name}': + delete: + description: |- + Delete a Key-set + + > Note: This API is not available in DB-less mode. + operationId: delete-key-set + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key-set + tags: + - Key-sets + get: + description: This endpoint retrieves information about a specific key-set based on its ID or name. + operationId: get-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Key-set + tags: + - Key-sets + patch: + description: |- + Update a Key-set using ID or name. + + > Note: This API is not available in DB-less mode. + + Inserts (or replaces) the Key Set under the requested resource with the definition specified in the body. The Key Set will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the Key Set being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new Key Set without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + operationId: update-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: |- + Update a Key-set using ID or name. + + > Note: This API is not available in DB-less mode. + operationId: upsert-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/key-set_id_or_name' + /keys: + get: + description: List all Keys + operationId: list-key + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Key' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Keys + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Keys + tags: + - Keys + post: + description: | + This API endpoint allows you to create a new key. When the request is successful, the API will respond with a 200 status code and a JSON object that represents the newly created key. If the request is invalid, the API will respond with a `400` status code and an error message in the response body. + + > Note: This API is not available in DB-less mode. + operationId: create-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + '/keys/{key_id_or_name}': + delete: + description: Delete a Key + operationId: delete-key + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Key + tags: + - Keys + get: + description: Get a Key using ID or name. + operationId: get-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + example: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully fetched Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Key + tags: + - Keys + patch: + description: Update a Key + operationId: update-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example: + value: + id: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + created_at: 1422386534 + updated_at: 1422386534 + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: Create or Update Key using ID or name. + operationId: upsert-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/key_id_or_name' + /plugins: + get: + description: This endpoint allows you to list all the plugins. You can use query parameters to filter the results by size or tags, for example `/plugins?size=50&tags=enterprise`. + operationId: list-plugin + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Plugins + tags: + - Plugins + post: + description: |- + Create a new Plugin + + >Note: This API is not available in DB-less mode. + operationId: create-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + '/plugins/{plugin_id}': + delete: + description: Delete a Plugin + operationId: delete-plugin + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Plugin + tags: + - Plugins + get: + description: Get a Plugin using ID. + operationId: get-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Plugin + tags: + - Plugins + patch: + description: Update a Plugin + operationId: update-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update Plugin using ID. + operationId: upsert-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/plugin_id' + /routes: + get: + description: |- + List all routes + + route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to its associated service. + + > Note: Path handling algorithms v1 was deprecated in Kong 3.0. From Kong 3.0, when router_flavor is set to expressions, route.path_handling will be unconfigurable and the path handling behavior will be "v0"; when router_flavor is set to traditional_compatible, the path handling behavior will be "v0" regardless of the value of route.path_handling. Only router_flavor = traditional will support path_handling "v1" behavior. + operationId: list-route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes + tags: + - Routes + post: + description: Create a new route + operationId: create-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + '/routes/{route_id_or_name}': + delete: + description: |- + Delete a route + + + > Note: This API is not available in DB-less mode. + operationId: delete-route + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route + tags: + - Routes + get: + description: Get a route using ID or name. + operationId: get-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route + tags: + - Routes + patch: + description: |- + Update a route + + > Note: This API is not available in DB-less mode. + operationId: update-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: |- + Create or Update route using ID or name. + + + > Note: This API is not available in DB-less mode. + operationId: upsert-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins': + get: + description: List all Plugins associated with a route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Plugins + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Plugins associated with a route + tags: + - Plugins + operationId: list-plugins-for-route + post: + description: Create a new Plugin associated with a route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully created Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Create a new Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-route + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + '/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a route using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Plugin associated with a route + tags: + - Plugins + operationId: delete-plugin-for-route + get: + description: Get a Plugin associated with a route using ID. + parameters: + - description: ID or name of the related route + in: path + name: route_id_or_name + required: true + schema: + type: string + - description: ID of the route to lookup + in: path + name: plugin_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a route + tags: + - Plugins + operationId: fetch-plugin-for-route + patch: + description: Update a Plugin associated with a route using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-route + put: + description: Create or Update a Plugin associated with a route using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + /services: + get: + description: List all services + operationId: list-service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + application/xml: + schema: + type: object + properties: {} + description: A successful response listing services + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all services + tags: + - Services + post: + description: Create a new service + operationId: create-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + '/services/{service_id_or_name}': + delete: + description: Delete a service + operationId: delete-service + parameters: + - description: ID or name of the service to delete + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted service or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a service + tags: + - Services + get: + description: Get a service using ID or name. + operationId: get-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a service + tags: + - Services + patch: + description: Update a service + operationId: update-service + parameters: + - description: ID or name of the service to update + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update service using ID or name. + operationId: upsert-service + parameters: + - description: Name or ID of the service to lookup + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}plugins': + get: + description: List all Plugins associated with a service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Plugins + summary: List all Plugins associated with a service + tags: + - Plugins + operationId: get-plugins-for-service + post: + description: Create a new Plugin associated with a service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a service using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a plugin associated with a service + tags: + - Plugins + operationId: delete-plugin-for-a-service + get: + description: Get a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '404': + description: Resource does not exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Fetch a Plugin associated with a service + tags: + - Plugins + operationId: fetch-plugin-with-a-service + patch: + description: Update a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-a-service + put: + description: Create or Update a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-a-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a service + parameters: + - description: ID or name of the related service + in: path + name: service_id_or_name + required: true + schema: + type: string + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + examples: + Example 1: + value: + data: + - hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + offset: string + description: A successful response listing routes + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all routes associated with a service + tags: + - Routes + operationId: list-routes-for-service + post: + description: Create a new route associated with a service + parameters: + - description: ID or name of the related service + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + example: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a service using ID or name. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a route associated with a service + tags: + - Routes + operationId: delete-route-for-service + get: + description: Get a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully fetched route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a route associated with a service + tags: + - Routes + operationId: fetch-route-for-service + patch: + description: Update a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-for-service + put: + description: Create or Update a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - bar.example.com + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + /snis: + get: + description: List all SNIs + operationId: list-sni + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all SNIs + tags: + - SNIs + post: + description: Create a new SNI + operationId: create-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + '/snis/{sni_name_or_id}': + delete: + description: Delete an SNI + operationId: delete-sni + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an SNI + tags: + - SNIs + get: + description: Get an SNI using ID or name. + operationId: get-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an SNI + tags: + - SNIs + patch: + description: Update an SNI + operationId: update-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name. + operationId: upsert-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/sni_name_or_id' + /upstreams: + get: + description: | + List all registered upstreams. You can filter the results by pagination size, offset, or tags like `/upstreams?size=10&offset=0`. + operationId: list-upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + examples: + example: + value: + data: + - algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + offset: string + description: A successful response listing Upstreams + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Upstreams + tags: + - Upstreams + post: + description: | + Create a new Upstream + operationId: create-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + '/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream + operationId: delete-upstream + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete an Upstream + tags: + - Upstreams + get: + description: Get an Upstream using ID or name. + operationId: get-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch an Upstream + tags: + - Upstreams + patch: + description: Update an Upstream + operationId: update-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + examples: + Example 1: + value: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name. + operationId: upsert-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + examples: + Example 1: + value: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream + parameters: + - description: ID or name of the related Upstream + in: path + name: upstream_id_or_name + required: true + schema: + type: string + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Target' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Targets + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Targets associated with an Upstream + tags: + - Targets + operationId: list-targets-for-upstream + post: + description: Create a new Target associated with an Upstream + parameters: + - description: ID or name of the related Upstream + in: path + name: upstream_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + examples: + Successfully created Target: + value: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + created_at: 1422386534 + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-for-upstream + parameters: + - name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + '/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Target associated with a an Upstream + tags: + - Targets + operationId: delete-upstream-target + get: + description: Get a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream + tags: + - Targets + operationId: fetch-target-for-upstream + patch: + description: Update a Target associated with a an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-for-upstream + put: + description: Create or Update a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-for-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + /vaults: + get: + description: List all Vaults + operationId: list-vault + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + '401': + $ref: '#/components/responses/HTTP401Error' + summary: List all Vaults + tags: + - Vaults + post: + description: Create a new Vault + operationId: create-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Create a new Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + '/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault + operationId: delete-vault + parameters: + - description: ID or prefix of the Vault to delete + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Delete a Vault + tags: + - Vaults + get: + description: |- + Get a Vault using ID or prefix. + + Vault entities are used to configure different Vault connectors. + operationId: get-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Fetch a Vault + tags: + - Vaults + patch: + description: Update a Vault + operationId: update-vault + parameters: + - description: ID or prefix of the Vault to update + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Resource does not exist + summary: Update a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix. + operationId: upsert-vault + parameters: + - description: Name or ID of the Vault to lookup + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '401': + $ref: '#/components/responses/HTTP401Error' + summary: Upsert a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/vault_id_or_prefix' + /endpoints: + get: + summary: List all endpoints + tags: + - Information + responses: + '200': + $ref: '#/components/responses/get-endpoints' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-endpoints + description: List all available endpoints provided by the Admin API. + '/{endpoint}': + parameters: + - schema: + type: string + example: key + name: endpoint + in: path + required: true + description: Any available endpoint + head: + summary: Check endpoint or entity existence + operationId: head-endpoints + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:38:29 GMT' + Content-Type: + description: The media type of the message content + schema: + type: string + example: text/html; charset=UTF-8 + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: aqETeVmkeiGnAMzdUT2JRWroB2myY1lB + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: Endpoint does not exist + headers: {} + description: | + Similar to `HTTP` GET, but does not return the body. Returns HTTP 200 when the endpoint exits or HTTP 404 when it does not. Other status codes are possible. + tags: + - Information + options: + summary: List method by endpoint + operationId: options-endpoint + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:24:17 GMT' + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + Access-Control-Allow-Headers: + description: Used in response to a preflight request to indicate which HTTP headers can be used during the actual request + schema: + type: string + example: 'Content-Type, Kong-Admin-Token, Kong-Request-Type, Cache-Control' + X-Kong-Admin-Request-ID: + description: A unique identifier for the request, generated by Kong + schema: + type: string + example: gDP1cF3OsNbrgcKPhRNE0RXRNfS7NcoG + Allow: + description: Lists the HTTP methods that are supported for the resource + schema: + type: string + example: 'OPTIONS, PATCH, POST' + Access-Control-Allow-Methods: + description: Indicates the methods allowed when accessing the resource in response to a preflight request + schema: + type: string + example: 'OPTIONS, PATCH, POST' + X-Kong-Admin-Latency: + description: The time taken to process the request on the server, in milliseconds + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '400': + description: Bad Request + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request. + tags: + - Information + '/schemas/{entity}': + parameters: + - schema: + type: string + name: entity + in: path + required: true + get: + summary: Retrieve entity schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + - id: + auto: true + type: string + uuid: true + properties: + fields: + type: array + description: A value of a schema + items: + type: object + properties: + id: + type: object + description: A value of a schema + properties: + auto: + type: boolean + description: A value of a schema + type: + type: string + description: A value of a schema + uuid: + type: boolean + description: A value of a schema + examples: + A mock schema: + value: + fields: + - id: + auto: true + type: string + uuid: true + - created_at: + auto: true + timestamp: true + type: integer + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-entity + description: Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations with Kong. + '/schemas/{entity}/validate': + parameters: + - schema: + type: string + name: entity + in: path + required: true + post: + summary: Validate a configuration against a schema + operationId: post-schemas-entity-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + Message: + type: string + example: schema validation successful + description: A success message + examples: + schema validation successful: + value: + Message: schema validation successful + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + tags: + - Information + '/schemas/filters/{filter_name}': + parameters: + - schema: + type: string + example: go-rate-limiting + name: filter_name + in: path + required: true + description: The name of a Proxy-Wasm filter + get: + summary: Retrieve Proxy-Wasm Filter JSON Schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + description: | + JSON Schema object describing the expected configuration for the filter. This endpoints always returns a JSON Schema object describing the filter configuration, even if the filter does not include JSON Schema metadata: if the configuration is expected as a raw string, the JSON Schema configuration returned by this endpoint will indicate so. + examples: + filter returning a JSON Schema included in the filter metadata: + value: + $schema: "http://json-schema.org/draft-04/schema#" + type: "object" + properties: + add: + type: "object" + properties: + headers: + type: "array" + items: + type: "string" + required: [headers] + required: [add] + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-filters-filter_name + description: | + Retrieve the JSON Schema of a Proxy-Wasm filter's configuration. This is useful to understand what fields a filter accepts, and can be used for building third-party integrations to the Kong's filter chain system. + '/schemas/plugins/{plugin_name}': + parameters: + - schema: + type: string + example: basic-auth + name: plugin_name + in: path + required: true + description: The name of a Kong plugin + get: + summary: Retrieve Plugin Schema + tags: + - Information + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-schemas-plugins-plugin_name + description: | + Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system. + /schemas/plugins/validate: + post: + summary: Validate plugin schema + operationId: post-schemas-plugins-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: schema validation successful + properties: + message: + type: string + description: A successful message + example: schema validation successful + examples: + schema validation successful: + value: + message: schema validation successful + '401': + $ref: '#/components/responses/HTTP401Error' + description: |- + Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + + This only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + tags: + - Information + /timers: + get: + summary: Retrieve Runtime Debugging Info of Kong's Timers + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + stats: + sys: + total: 13 + waiting: 12 + runs: 6771 + pending: 0 + running: 1 + flamegraph: + pending: '' + running: '' + elapsed_time: '' + timers: + router-rebuild: + is_running: false + name: router-rebuild + stats: + runs: 464 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 464 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off': + is_running: false + name: 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off' + stats: + runs: 3 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 3 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + worker: + id: 0 + count: 5 + properties: + stats: + type: object + description: Statistics about the worker + properties: + sys: + type: object + description: List of the number of different type of timers + properties: + total: + description: The total number of timers (running + pending + waiting) + type: integer + default: 7 + example: 7 + waiting: + description: The number of unexpired timers + type: integer + default: 7 + example: 7 + runs: + description: The total number of runs for the timers + type: integer + default: 7 + example: 7 + pending: + description: The number of pending timers + type: integer + default: 0 + example: 0 + running: + description: The number of running timers + type: integer + default: 0 + example: 0 + flamegraph: + type: object + description: String-encoded timer-related flamegraph data + properties: + pending: + description: The number of pending timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + running: + description: The number of running timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + elapsed_time: + description: The elapsed time for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17 + timers: + description: Timer statistics for the worker + type: object + properties: + meta: + description: Program callstack of created timers + type: object + properties: + name: + description: The name of the timer's metadata + type: string + example: '@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()' + worker: + type: object + properties: + id: + type: integer + description: The ordinal number of the current Nginx worker processes (starting from number 0). + count: + type: integer + description: The total number of the Nginx worker processes. + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-timers + description: Retrieve runtime stats data from [lua-resty-timer-ng](https://github.com/Kong/lua-resty-timer-ng). + /status: + get: + summary: Health Routes + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + properties: + memory: + type: object + description: Metrics about the memory usage. + properties: + lua_shared_dicts: + type: object + description: An array of information about dictionaries that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (capacity) and how much of said memory is in use (allocated_slabs). + properties: + kong_core_db_cache: + type: object + properties: + capacity: + type: string + example: 128.00 MiB + description: Memory capacity + allocated_slabs: + type: string + example: 128.00 MiB + description: Total allocated memory + workers_lua_vms: + type: array + description: An array with all workers of the Kong node, each entry contains a `http_allocated_gc` string and a `pid`. + items: + type: object + properties: + http_allocated_gc: + type: string + description: | + HTTP submodule's Lua virtual machine's memory usage information, as reported by + pid: + type: integer + description: worker's process identification number. + example: 18478 + database: + type: object + description: Metrics about the database + properties: + reachable: + type: boolean + description: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself. + server: + type: object + description: Metrics about the nginx HTTP/S server + properties: + connections_reading: + type: integer + description: The current number of connections where Kong is reading the request header. + example: 3 + connections_writing: + type: integer + description: The current number of connections where nginx is writing the response back to the client. + example: 1 + total_requests: + type: integer + description: The total number of client requests. + example: 1 + connections_waiting: + type: integer + description: The current number of idle client connections waiting for a request. + example: 1 + connections_handled: + type: integer + description: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached. + example: 1 + connections_active: + type: integer + description: The current number of active client connections including Waiting connections. + example: 1 + connections_accepted: + type: integer + description: The total number of accepted client connections. + example: 1 + examples: + Status endpoint response: + value: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-status + description: |- + Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, the status of the database connection, and node's memory usage. + + If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used. + /status/dns: + get: + summary: DNS Status + tags: + - Information + operationId: getDnsStatus + description: | + Retrieve DNS worker and stats information. If the legacy DNS client is in use, it returns a 501 status with a message. + responses: + '200': + description: DNS worker and stats information + content: + application/json: + schema: + type: object + properties: + worker: + type: object + description: Worker information. + properties: + id: + type: integer + description: The worker ID. + example: 1 + count: + type: integer + description: The total number of workers. + example: 4 + stats: + type: object + description: DNS stats information (specific details depend on the Kong instance). + '501': + description: Legacy DNS client in use + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Message indicating that the endpoint is not implemented with the legacy DNS client. + example: "not implemented with the legacy DNS client" + '401': + $ref: '#/components/responses/HTTP401Error' + /tags: + get: + summary: List all tags + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags + description: |- + Returns a paginated list of all the tags in the system. + + The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list. + + If an entity is tagged with more than one tag, the entity_id for that entity will appear more than once in the resulting list. Similarly, if several entities have been tagged with the same tag, the tag will appear in several items of this list. + '/tags/{tags}': + parameters: + - $ref: '#/components/parameters/tag' + get: + summary: List entity by tag + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-tags-tags + description: |- + Returns the entities that have been tagged with the specified tag. + + The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list. + '/debug/cluster/control-planes-nodes/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set Node Log Level of All Control Plane Nodes + operationId: put-debug-cluster-control-planes-nodes-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + description: Response message + example: log level changed + examples: + log level changed: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Change the log level of all control plane nodes deployed in a hybrid (CP/DP) cluster. + + See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. + + Care must be taken when changing the log level of a node to `debug` in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level such as notice. + + It's currently not possible to change the log level of DP and DB-less nodes. + tags: + - Debug + '/debug/cluster/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set Node Log Level of All Nodes + operationId: put-debug-cluster-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + example: log level changed + description: A message containing information about the log level + examples: + log level changed: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Change the log level of all nodes in a cluster. + + + + See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. + + It's currently not possible to change the log level of DP and DB-less nodes. + + Currently, when a user dynamically changes the log level for the entire cluster, if a new node joins a cluster the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. + tags: + - Debug + /debug/node/log-level: + get: + summary: Retrieve Node Log Level of A Node + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: 'log level: debug' + properties: + message: + type: string + example: 'log level: debug' + description: A message containing the current log level of the node. + examples: + Example 1: + value: + message: 'log level: debug' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-debug-node-log-level + description: |- + Retrieve the current log level of a node. + + See the [NGINX documentation](http://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + tags: + - Debug + parameters: [] + '/debug/node/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set log level of a single node + operationId: put-debug-node-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + description: A message confirming the log level change + example: log level changed + examples: + log level changed: + value: + message: log level changed + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Change the log level of a node. + + See the [NGINX documentation](http://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + tags: + - Debug + '/schemas/vaults/{vault_name}': + parameters: + - schema: + type: string + name: vault_name + in: path + required: true + description: The vault schema to be returned + get: + summary: Retrieve Vault Schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + '401': + $ref: '#/components/responses/HTTP401Error' + '404': + description: No vault named + operationId: get-schemas-vaults-vault_name + description: Retrieve the schema of a vault. + post: + summary: Validate Vault Schema + tags: + - Validation + requestBody: + description: Payload containing the schema data to validate + required: true + content: + application/json: + schema: + type: object + properties: + schemaData: + type: string + description: JSON string containing the vault schema data + responses: + '200': + description: Validation successful + content: + application/json: + schema: + type: object + properties: + validation: + type: boolean + description: Indicates if the schema is valid + '400': + description: Bad request due to invalid schema data + '405': + description: Method Not Allowed + operationId: post-schemas-vaults-validate + description: Validates the given vault schema data against predefined validation rules. + /filter-chains: + post: + summary: Add Filter Chain + operationId: post-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Create Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains + operationId: get-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + List All Filter Chains + '/routes/{route_id_or_name}/filter-chains': + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + post: + summary: Add Filter Chain + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_name_or_id-filter-chains + description: | + Create Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Route + operationId: get-routes-route_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + tags: + - filter-chains + description: | + List Filter Chains Associated to a Specific Route + patch: + summary: Update Filter Chain Associated to a Specific Route + operationId: patch-routes-route_id_or_name-filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain Associated to a Specific Route + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + '/services/{service_id_or_name}/filter-chains': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + post: + summary: Create Filter Chain Associated to a Specific Service + tags: + - filter-chains + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-services-service_id_or_name-filter-chains + description: | + Add filter chain Associated to a Specific Service + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + get: + summary: List Filter Chains Associated to a Specific Service + operationId: get-service_id_or_name-filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + List Filter Chains Associated to a Specific Service + tags: + - filter-chains + '/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: Retrieve Filter Chain + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + operationId: get-filter-chains-filter_chain_id + description: | + Retrieve Filter Chain + '401': + $ref: '#/components/responses/HTTP401Error' + patch: + summary: Update Filter Chain + operationId: patch-filter-chains-filter_chain_id + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: | + Update Filter Chain + Note: This API is not available in DB-less mode. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + put: + summary: Update Or Create Filter Chain + operationId: put-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + tags: + - filter-chains + description: |- + Inserts (or replaces) the filter chain under the requested resource with the definition specified in the body. The filter chain is identified via the name or ID attribute. + + When the name or ID attribute has the structure of a UUID, the filter chain being inserted or replaced is identified by its ID. Otherwise, it is identified by its name. + + When creating a new filter chain without specifying an ID (neither in the URL nor in the body), the ID will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + delete: + summary: Delete Filter Chain + operationId: delete-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain. + tags: + - filter-chains + '/routes/{route_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + get: + summary: List Filter Chains Associated to a Specific Route + tags: + - filter-chains + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Filter-chains' + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter-chains-filter_chain_id + description: | + Retrieve filter chain associated to a specific route. + put: + summary: Create Or Update Filter Chain Associated to a Specific Route + operationId: put-routes-route_id_or_name-filter-chains-filter_chain_id + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Create or update filter chain associated to a specific route. + requestBody: + $ref: '#/components/requestBodies/filter-chains-request' + tags: + - filter-chains + '/routes/{route_id_or_name}/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/filter_chain_id' + - $ref: '#/components/parameters/route_id_or_name' + delete: + summary: Delete Filter Chain Associated to a Specific Route + tags: + - filter-chains + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + operationId: get-routes-route_id_or_name-filter_chain_id + description: | + Delete filter chain associated to a specific route. + '/services/{service_id_or_name}/filter-chains/{filter_chain_id}': + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/filter_chain_id' + delete: + summary: Delete Filter Chain Associated to a Specific Service + operationId: delete-services-service_id_or_name-filter-chains-filter_chain_id + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/HTTP401Error' + description: | + Delete filter chain associated to a specific service. + tags: + - filter-chains + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache +servers: + - description: Default Admin API URL + url: '{protocol}://{hostname}:{port}{path}' + variables: + hostname: + default: localhost + description: Hostname for Kong's Admin API + path: + default: / + description: Base path for Kong's Admin API + port: + default: '8001' + description: Port for Kong's Admin API + protocol: + default: http + description: Protocol for requests to Kong's Admin API + enum: + - http + - https +tags: + - description: | + Service entities are abstractions of your microservice interfaces or formal APIs. For example, a service could be a data transformation microservice or a billing API. +

+ The main attribute of a service is the destination URL for proxying traffic. This URL can be set as a single string or by specifying its protocol, host, port and path individually. +

+ Services are associated to routes, and a single service can have many routes associated with it. Routes are entrypoints in Kong Gateway which define rules to match client requests. Once a route is matched, Kong Gateway proxies the request to its associated service. See the [Proxy Reference](https://docs.konghq.com/gateway/latest/how-kong-works/routing-traffic/) for a detailed explanation of how Kong proxies traffic. +

+ Services can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). + name: Services + - description: | + Route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to the associated service. You need at least one matching rule that applies to the protocol being matched by the route. +

+ The combination of routes and services, and the separation of concerns between them, offers a powerful routing mechanism with which it is possible to define fine-grained entrypoints in Kong Gateway leading to different upstream services of your infrastructure. +

+ Depending on the protocol, one of the following attributes must be set: +
+ * `http`: At least one of `methods`, `hosts`, `headers`, or `paths` + * `https`: At least one of `methods`, `hosts`, `headers`, `paths`, or `snis` + * `tcp`: At least one of `sources` or `destinations` + * `tls`: at least one of `sources`, `destinations`, or `snis` + * `tls_passthrough`: set `snis` + * `grpc`: At least one of `hosts`, `headers`, or `paths` + * `grpcs`: At least one of `hosts`, `headers`, `paths`, or `snis` +
+ + A route can't have both `tls` and `tls_passthrough` protocols at same time. +

+ + Learn more about the router: + * [Configure routes using expressions](https://docs.konghq.com/gateway/latest/key-concepts/routes/expressions/) + * [Router Expressions language reference](https://docs.konghq.com/gateway/latest/reference/expressions-language/) + name: Routes + - description: | + A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. Plugins let you add functionality to services that run behind a Kong Gateway instance, like authentication or rate limiting. + You can find more information about available plugins and which values each plugin accepts at the [Plugin Hub](https://docs.konghq.com/hub/). +

+ When adding a plugin configuration to a service, the plugin will run on every request made by a client to that service. If a plugin needs to be tuned to different values for some specific consumers, you can do so by creating a separate plugin instance that specifies both the service and the consumer, through the service and consumer fields. +

+ Plugins can be both [tagged and filtered by tags](https://docs.konghq.com/gateway/latest/admin-api/#tags). + name: Plugins + - description: | + The consumer object represents a consumer - or a user - of a service. + You can either rely on Kong Gateway as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong Gateway and your existing primary datastore. + name: Consumers + - description: | + A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong Gateway to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. +

+ Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. +

+ If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string. + name: Certificates + - description: | + An SNI object represents a many-to-one mapping of hostnames to a certificate. +

+ A certificate object can have many hostnames associated with it. When Kong Gateway receives an SSL request, it uses the SNI field in the Client Hello to look up the certificate object based on the SNI associated with the certificate. + name: SNIs + - description: | + A CA certificate object represents a trusted certificate authority. + These objects are used by Kong Gateway to verify the validity of a client or server certificate. + name: CA Certificates + - description: | + The upstream object represents a virtual hostname and can be used to load balance incoming requests over multiple services (targets). +

+ An upstream also includes a [health checker](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/), which can enable and disable targets based on their ability or inability to serve requests. + The configuration for the health checker is stored in the upstream object, and applies to all of its targets. + name: Upstreams + - description: | + Vault objects are used to configure different vault connectors for [managing secrets](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/). + Configuring a vault lets you reference secrets from other entities. + This allows for a proper separation of secrets and configuration and prevents secret sprawl. +

+ For example, you could store a certificate and a key in a vault, then reference them from a certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure. +

+ Secrets rotation can be managed using [TTLs](https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/advanced-usage/). + name: Vaults + - description: | + A key object holds a representation of asymmetric keys in various formats. When Kong Gateway or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity. + name: Keys + - description: | + A JSON Web key set. Key sets are the preferred way to expose keys to plugins because they tell the plugin where to look for keys or have a scoping mechanism to restrict plugins to specific keys. + name: Key-sets + - description: Information routes + name: Information + - description: Debug routes + name: Debug + - description: | + A target is an IP address or hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. +

+ To disable a target, post a new one with `weight=0`, or use the `DELETE` method to accomplish the same. + name: Targets + - description: | + Tags are strings associated to entities in Kong Gateway. Tags can contain almost all UTF-8 characters, with the following exceptions: `,`,`/`, and non-printable ASCII (for example, the space character). +

+ Most core entities can be tagged via the tags attribute upon creation or modification. + name: Tags + - description: | + Retreieve information about the status of data planes when Kong Gateway is configured in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache