Admin API

Kong Gateway comes with an internal RESTful Admin API for administration purposes. Requests to the Admin API can be sent to any node in the cluster, and Kong will keep the configuration consistent across all nodes.

  • 8001 is the default port on which the Admin API listens.
  • 8444 is the default port for HTTPS traffic to the Admin API.

This API is designed for internal use and provides full control over Kong, so care should be taken when setting up Kong environments to avoid undue public exposure of this API. See this document for a discussion of methods to secure the Admin API.


DB-less Mode

In DB-less mode, the Admin API can be used to load a new declarative configuration, and for inspecting the current configuration. In DB-less mode, the Admin API for each Kong node functions independently, reflecting the memory state of that particular Kong node. This is the case because there is no database coordination between Kong nodes.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:


Declarative Configuration

Loading the declarative configuration of entities into Kong Gateway can be done in two ways: at start-up, through the declarative_config property, or at run-time, through the Admin API using the /config endpoint.

To get started using declarative configuration, you need a file (in YAML or JSON format) containing entity definitions. You can generate a sample declarative configuration with the command:

  1. kong config init

It generates a file named kong.yml in the current directory, containing the appropriate structure and examples.

Reload Declarative Configuration

This endpoint allows resetting a DB-less Kong with a new declarative configuration data file. All previous contents are erased from memory, and the entities specified in the given file take their place.

To learn more about the file format, see the declarative configuration documentation.

/config

AttributesDescription
config
required
The config data (in YAML or JSON format) to be loaded.

Request Querystring Parameters

AttributesDescription
check_hash
optional
If set to 1, Kong will compare the hash of the input config data against that of the previous one. If the configuration is identical, it will not reload it and will return HTTP 304.

Response

  1. HTTP 200 OK
  1. {
  2. {
  3. "services": [],
  4. "routes": []
  5. }
  6. }

The response contains a list of all the entities that were parsed from the input file.


Supported Content Types

The Admin API accepts 3 content types on every endpoint:

  • application/json

Handy for complex bodies (ex: complex plugin configuration), in that case simply send a JSON representation of the data you want to send. Example:

  1. {
  2. "config": {
  3. "limit": 10,
  4. "period": "seconds"
  5. }
  6. }

An example adding a Route to a Service named test-service:

  1. curl -i -X POST http://localhost:8001/services/test-service/routes \
  2. -H "Content-Type: application/json" \
  3. -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ]}'
  • application/x-www-form-urlencoded

Simple enough for basic request bodies, you will probably use it most of the time. Note that when sending nested values, Kong expects nested objects to be referenced with dotted keys. Example:

  1. config.limit=10&config.period=seconds

When specifying arrays, send the values in order, or use square brackets (numbering inside the brackets is optional but if provided it must be 1-indexed, and consecutive). An example Route added to a Service named test-service:

  1. curl -i -X POST http://localhost:8001/services/test-service/routes \
  2. -d "name=test-route" \
  3. -d "paths[1]=/path/one" \
  4. -d "paths[2]=/path/two"

The following two examples are identical to the one above, but less explicit:

  1. curl -i -X POST http://localhost:8001/services/test-service/routes \
  2. -d "name=test-route" \
  3. -d "paths[]=/path/one" \
  4. -d "paths[]=/path/two"
  5. curl -i -X POST http://localhost:8001/services/test-service/routes \
  6. -d "name=test-route" \
  7. -d "paths=/path/one" \
  8. -d "paths=/path/two"
  • multipart/form-data

Similar to URL-encoded, this content type uses dotted keys to reference nested objects. Here is an example of sending a Lua file to the pre-function Kong plugin:

  1. curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
  2. -F "name=pre-function" \
  3. -F "config.access=@custom-auth.lua"

When specifying arrays for this content-type, the array indices must be specified. An example Route added to a Service named test-service:

  1. curl -i -X POST http://localhost:8001/services/test-service/routes \
  2. -F "name=test-route" \
  3. -F "paths[1]=/path/one" \
  4. -F "paths[2]=/path/two"

Information Routes

Retrieve Node Information

Retrieve generic details about a node.

/

Response

  1. HTTP 200 OK
  1. {
  2. "hostname": "",
  3. "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969",
  4. "lua_version": "LuaJIT 2.1.0-beta3",
  5. "plugins": {
  6. "available_on_server": [
  7. ...
  8. ],
  9. "enabled_in_cluster": [
  10. ...
  11. ]
  12. },
  13. "configuration" : {
  14. ...
  15. },
  16. "tagline": "Welcome to Kong",
  17. "version": "0.14.0"
  18. }
  • node_id: A UUID representing the running Kong node. This UUID is randomly generated when Kong starts, so the node will have a different node_id each time it is restarted.
  • available_on_server: Names of plugins that are installed on the node.
  • enabled_in_cluster: Names of plugins that are enabled/configured. That is, the plugins configurations currently in the data store shared by all Kong nodes.

Check Endpoint Or Entity Existence

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.

/<any-endpoint>

Response

  1. HTTP 200 OK
  1. Access-Control-Allow-Origin: *
  2. Content-Length: 11389
  3. Content-Type: application/json; charset=utf-8
  4. X-Kong-Admin-Latency: 1

List Http Methods by Endpoint

List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request.

/<any-endpoint>

Response

  1. HTTP 204 No Content
  1. Access-Control-Allow-Headers: Content-Type
  2. Access-Control-Allow-Methods: GET, HEAD, OPTIONS
  3. Access-Control-Allow-Origin: *
  4. Allow: GET, HEAD, OPTIONS

List Available Endpoints

List all available endpoints provided by the Admin API.

/endpoints

Response

  1. HTTP 200 OK
  1. {
  2. "data": [
  3. "/",
  4. "/acls",
  5. "/acls/{acls}",
  6. "/acls/{acls}/consumer",
  7. "/basic-auths",
  8. "/basic-auths/{basicauth_credentials}",
  9. "/basic-auths/{basicauth_credentials}/consumer",
  10. "/ca_certificates",
  11. "/ca_certificates/{ca_certificates}",
  12. "/cache",
  13. "/cache/{key}",
  14. "..."
  15. ]
  16. }

Validate A Configuration against A Schema

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.

Note that 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.

/schemas/{entity}/validate

Response

  1. HTTP 200 OK
  1. {
  2. "message": "schema validation successful"
  3. }

Retrieve Entity Schema

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 to the Kong.

/schemas/{entity name}

Response

  1. HTTP 200 OK
  1. {
  2. "fields": [
  3. {
  4. "id": {
  5. "auto": true,
  6. "type": "string",
  7. "uuid": true
  8. }
  9. },
  10. {
  11. "created_at": {
  12. "auto": true,
  13. "timestamp": true,
  14. "type": "integer"
  15. }
  16. },
  17. ...
  18. ]
  19. }

Retrieve Plugin Schema

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/{plugin name}

Response

  1. HTTP 200 OK
  1. {
  2. "fields": {
  3. "hide_credentials": {
  4. "default": false,
  5. "type": "boolean"
  6. },
  7. "key_names": {
  8. "default": "function",
  9. "required": true,
  10. "type": "array"
  11. }
  12. }
  13. }

Validate A Plugin Configuration against The Schema

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.

Note that 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.

/schemas/plugins/validate

Response

  1. HTTP 200 OK
  1. {
  2. "message": "schema validation successful"
  3. }

Retrieve Runtime Debugging Info of Kong’s Timers

Retrieve runtime stats data from lua-resty-timer-ng.

/timers

Response

  1. HTTP 200 OK
  1. { "worker": {
  2. "id": 0,
  3. "count": 4,
  4. },
  5. "stats": {
  6. "flamegraph": {
  7. "running": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0\n",
  8. "elapsed_time": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17\n",
  9. "pending": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0\n"
  10. },
  11. "sys": {
  12. "running": 0,
  13. "runs": 7,
  14. "pending": 0,
  15. "waiting": 7,
  16. "total": 7
  17. },
  18. "timers": {
  19. "healthcheck-localhost:8080": {
  20. "name": "healthcheck-localhost:8080",
  21. "meta": {
  22. "name": "@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()",
  23. "callstack": "@./kong/plugins/prometheus/prometheus.lua:673:init_worker();@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()"
  24. },
  25. "stats": {
  26. "finish": 2,
  27. "runs": 2,
  28. "elapsed_time": {
  29. "min": 0,
  30. "max": 0,
  31. "avg": 0,
  32. "variance": 0
  33. },
  34. "last_err_msg": ""
  35. }
  36. }
  37. }
  38. }
  39. }
  • worker:
    • id: The ordinal number of the current Nginx worker processes (starting from number 0).
    • count: The total number of the Nginx worker processes.
  • stats.flamegraph: String-encoded timer-related flamegraph data. You can use brendangregg/FlameGraph to generate flamegraph SVGs.
  • stats.sys: List the number of different type of timers.
    • running: number of running timers.
    • pending: number of pending timers.
    • waiting: number of unexpired timers.
    • total: running + pending + waiting.
  • timers.meta: Program call stack of created timers.
    • name: An automatically generated string that stores the location where the creation timer was created.
    • callstack: Lua call stack string showing where this timer was created.
  • timers.stats.elapsed_time: An object that stores the maximum, minimum, average and variance of the time spent on each run of the timer (second).
  • timers.stats.runs: Total number of runs.
  • timers.stats.finish: Total number of successful runs.

Note: flamegraph, timers.meta and timers.stats.elapsed_time keys are only available when Kong’s log_level config is set to debug. Read the doc of lua-resty-timer-ng for more details.


Health Routes

Retrieve Node Status

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

Response

  1. HTTP 200 OK
  1. {
  2. "database": {
  3. "reachable": true
  4. },
  5. "memory": {
  6. "workers_lua_vms": [{
  7. "http_allocated_gc": "0.02 MiB",
  8. "pid": 18477
  9. }, {
  10. "http_allocated_gc": "0.02 MiB",
  11. "pid": 18478
  12. }],
  13. "lua_shared_dicts": {
  14. "kong": {
  15. "allocated_slabs": "0.04 MiB",
  16. "capacity": "5.00 MiB"
  17. },
  18. "kong_db_cache": {
  19. "allocated_slabs": "0.80 MiB",
  20. "capacity": "128.00 MiB"
  21. },
  22. }
  23. },
  24. "server": {
  25. "total_requests": 3,
  26. "connections_active": 1,
  27. "connections_accepted": 1,
  28. "connections_handled": 1,
  29. "connections_reading": 0,
  30. "connections_writing": 1,
  31. "connections_waiting": 0
  32. },
  33. "configuration_hash": "779742c3d7afee2e38f977044d2ed96b"
  34. }
  • memory: Metrics about the memory usage.
    • workers_lua_vms: An array with all workers of the Kong node, where each entry contains:
    • http_allocated_gc: HTTP submodule’s Lua virtual machine’s memory usage information, as reported by collectgarbage("count"), for every active worker, i.e. a worker that received a proxy call in the last 10 seconds.
    • pid: worker’s process identification number.
    • lua_shared_dicts: 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). These shared dictionaries have least recent used (LRU) eviction capabilities, so a full dictionary, where allocated_slabs == capacity, will work properly. However for some dictionaries, e.g. cache HIT/MISS shared dictionaries, increasing their size can be beneficial for the overall performance of a Kong node.
    • The memory usage unit and precision can be changed using the querystring arguments unit and scale:
      • unit: one of b/B, k/K, m/M, g/G, which will return results in bytes, kibibytes, mebibytes, or gibibytes, respectively. When “bytes” are requested, the memory values in the response will have a number type instead of string. Defaults to m.
      • scale: the number of digits to the right of the decimal points when values are given in human-readable memory strings (unit other than “bytes”). Defaults to 2. You can get the shared dictionaries memory usage in kibibytes with 4 digits of precision by doing: GET /status?unit=k&scale=4
  • server: Metrics about the nginx HTTP/S server.
    • total_requests: The total number of client requests.
    • connections_active: The current number of active client connections including Waiting connections.
    • connections_accepted: The total number of accepted client connections.
    • connections_handled: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.
    • connections_reading: The current number of connections where Kong is reading the request header.
    • connections_writing: The current number of connections where nginx is writing the response back to the client.
    • connections_waiting: The current number of idle client connections waiting for a request.
  • database: Metrics about the database.
    • reachable: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself.
  • configuration_hash: The hash of the current configuration. This field is only returned when the Kong node is running in DB-less or data-plane mode. The special return value “00000000000000000000000000000000” means Kong does not currently have a valid configuration loaded.

Tags

Tags are strings associated to entities in Kong.

Tags can contain almost all UTF-8 characters, with the following exceptions:

  • , and / are reserved for filtering tags with “and” and “or”, so they are not allowed in tags.
  • Non-printable ASCII (for example, the space character) is not allowed.

Most core entities can be tagged via their tags attribute, upon creation or edition.

Tags can be used to filter core entities as well, via the ?tags querystring parameter.

For example: if you normally get a list of all the Services by doing:

  1. GET /services

You can get the list of all the Services tagged example by doing:

  1. GET /services?tags=example

Similarly, if you want to filter Services so that you only get the ones tagged example and admin, you can do that like so:

  1. GET /services?tags=example,admin

Finally, if you wanted to filter the Services tagged example or admin, you could use:

  1. GET /services?tags=example/admin

Some notes:

  • A maximum of 5 tags can be queried simultaneously in a single request with , or /
  • Mixing operators is not supported: if you try to mix , with / in the same querystring, you will receive an error.
  • You may need to quote and/or escape some characters when using them from the command line.
  • Filtering by tags is not supported in foreign key relationship endpoints. For example, the tags parameter will be ignored in a request such as GET /services/foo/routes?tags=a,b
  • offset parameters are not guaranteed to work if the tags parameter is altered or removed

List All Tags

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

Response

  1. HTTP 200 OK
  1. {
  2. {
  3. "data": [
  4. { "entity_name": "services",
  5. "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
  6. "tag": "s1",
  7. },
  8. { "entity_name": "services",
  9. "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
  10. "tag": "s2",
  11. },
  12. { "entity_name": "routes",
  13. "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000",
  14. "tag": "s1",
  15. },
  16. ...
  17. ],
  18. "offset": "c47139f3-d780-483d-8a97-17e9adc5a7ab",
  19. "next": "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab",
  20. }
  21. }

List Entity Ids by Tag

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.

/tags/{tags}

Response

  1. HTTP 200 OK
  1. {
  2. {
  3. "data": [
  4. { "entity_name": "services",
  5. "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c",
  6. "tag": "example",
  7. },
  8. { "entity_name": "routes",
  9. "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1",
  10. "tag": "example",
  11. },
  12. ...
  13. ],
  14. "offset": "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
  15. "next": "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
  16. }
  17. }

Service Object

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 for a detailed explanation of how Kong proxies traffic.

Services can be both tagged and filtered by tags.

  1. {
  2. "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-service",
  6. "retries": 5,
  7. "protocol": "http",
  8. "host": "example.com",
  9. "port": 80,
  10. "path": "/some_api",
  11. "connect_timeout": 60000,
  12. "write_timeout": 60000,
  13. "read_timeout": 60000,
  14. "tags": ["user-level", "low-priority"],
  15. "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
  16. "tls_verify": true,
  17. "tls_verify_depth": null,
  18. "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
  19. "enabled": true
  20. }

Add Service

Note: This API is not available in DB-less mode.

Create Service

/services

Create Service Associated to a Specific Certificate

/certificates/{certificate name or id}/services

AttributesDescription
certificate name or id
required
The unique identifier or the name attribute of the Certificate that should be associated to the newly-created Service.

Request Body

AttributesDescription
name
optional
The Service name.
retries
optional
The number of retries to execute upon failure to proxy. Default: 5.
protocolThe protocol used to communicate with the upstream. Accepted values are: “grpc”, “grpcs”, “http”, “https”, “tcp”, “tls”, “tls_passthrough”, “udp”, “ws” , “wss” . Default: “http”.
hostThe host of the upstream server. Note that the host value is case sensitive.
portThe upstream server port. Default: 80.
path
optional
The path to be used in requests to the upstream server.
connect_timeout
optional
The timeout in milliseconds for establishing a connection to the upstream server. Default: 60000.
write_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: 60000.
read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: 60000.
tags
optional
An optional set of strings associated with the Service for grouping and filtering.
client_certificate
optional
Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is client_certificate.id=<client_certificate id>. With JSON, use ““client_certificate”:{“id”:”<client_certificate id>”}.
tls_verify
optional
Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.
tls_verify_depth
optional
Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected. Default: null.
ca_certificates
optional
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). 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.
enabledWhether 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. Default: true.
url
shorthand-attribute
Shorthand attribute to set protocol, host, port and path at once. This attribute is write-only (the Admin API never returns the URL).

Response

  1. HTTP 201 Created
  1. {
  2. "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-service",
  6. "retries": 5,
  7. "protocol": "http",
  8. "host": "example.com",
  9. "port": 80,
  10. "path": "/some_api",
  11. "connect_timeout": 60000,
  12. "write_timeout": 60000,
  13. "read_timeout": 60000,
  14. "tags": ["user-level", "low-priority"],
  15. "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
  16. "tls_verify": true,
  17. "tls_verify_depth": null,
  18. "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
  19. "enabled": true
  20. }

List Services

List All Services

/services

List Services Associated to a Specific Certificate

/certificates/{certificate name or id}/services

AttributesDescription
certificate name or id
required
The unique identifier or the name attribute of the Certificate whose Services are to be retrieved. When using this endpoint, only Services associated to the specified Certificate will be listed.

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a",
  4. "created_at": 1422386534,
  5. "updated_at": 1422386534,
  6. "name": "my-service",
  7. "retries": 5,
  8. "protocol": "http",
  9. "host": "example.com",
  10. "port": 80,
  11. "path": "/some_api",
  12. "connect_timeout": 60000,
  13. "write_timeout": 60000,
  14. "read_timeout": 60000,
  15. "tags": ["user-level", "low-priority"],
  16. "client_certificate": {"id":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"},
  17. "tls_verify": true,
  18. "tls_verify_depth": null,
  19. "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
  20. "enabled": true
  21. }, {
  22. "id": "fc73f2af-890d-4f9b-8363-af8945001f7f",
  23. "created_at": 1422386534,
  24. "updated_at": 1422386534,
  25. "name": "my-service",
  26. "retries": 5,
  27. "protocol": "http",
  28. "host": "example.com",
  29. "port": 80,
  30. "path": "/another_api",
  31. "connect_timeout": 60000,
  32. "write_timeout": 60000,
  33. "read_timeout": 60000,
  34. "tags": ["admin", "high-priority", "critical"],
  35. "client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"},
  36. "tls_verify": true,
  37. "tls_verify_depth": null,
  38. "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
  39. "enabled": true
  40. }],
  41. "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  42. }

Retrieve Service

Retrieve Service

/services/{service name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to retrieve.
Retrieve Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to retrieve.
service name or id
required
The unique identifier or the name of the Service to retrieve.
Retrieve Service Associated to a Specific Route

/routes/{route name or id}/service

AttributesDescription
route name or id
required
The unique identifier or the name of the Route associated to the Service to be retrieved.
Retrieve Service Associated to a Specific Plugin

/plugins/{plugin id}/service

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Service to be retrieved.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-service",
  6. "retries": 5,
  7. "protocol": "http",
  8. "host": "example.com",
  9. "port": 80,
  10. "path": "/some_api",
  11. "connect_timeout": 60000,
  12. "write_timeout": 60000,
  13. "read_timeout": 60000,
  14. "tags": ["user-level", "low-priority"],
  15. "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
  16. "tls_verify": true,
  17. "tls_verify_depth": null,
  18. "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
  19. "enabled": true
  20. }

Update Service

Note: This API is not available in DB-less mode.

Update Service

/services/{service name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to update.
Update Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to update.
service name or id
required
The unique identifier or the name of the Service to update.
Update Service Associated to a Specific Route

/routes/{route name or id}/service

AttributesDescription
route name or id
required
The unique identifier or the name of the Route associated to the Service to be updated.
Update Service Associated to a Specific Plugin

/plugins/{plugin id}/service

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Service to be updated.

Request Body

AttributesDescription
name
optional
The Service name.
retries
optional
The number of retries to execute upon failure to proxy. Default: 5.
protocolThe protocol used to communicate with the upstream. Accepted values are: “grpc”, “grpcs”, “http”, “https”, “tcp”, “tls”, “tls_passthrough”, “udp”, “ws” , “wss” . Default: “http”.
hostThe host of the upstream server. Note that the host value is case sensitive.
portThe upstream server port. Default: 80.
path
optional
The path to be used in requests to the upstream server.
connect_timeout
optional
The timeout in milliseconds for establishing a connection to the upstream server. Default: 60000.
write_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: 60000.
read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: 60000.
tags
optional
An optional set of strings associated with the Service for grouping and filtering.
client_certificate
optional
Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is client_certificate.id=<client_certificate id>. With JSON, use ““client_certificate”:{“id”:”<client_certificate id>”}.
tls_verify
optional
Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.
tls_verify_depth
optional
Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected. Default: null.
ca_certificates
optional
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). 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.
enabledWhether 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. Default: true.
url
shorthand-attribute
Shorthand attribute to set protocol, host, port and path at once. This attribute is write-only (the Admin API never returns the URL).

Response

  1. HTTP 200 OK
  1. {
  2. "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-service",
  6. "retries": 5,
  7. "protocol": "http",
  8. "host": "example.com",
  9. "port": 80,
  10. "path": "/some_api",
  11. "connect_timeout": 60000,
  12. "write_timeout": 60000,
  13. "read_timeout": 60000,
  14. "tags": ["user-level", "low-priority"],
  15. "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
  16. "tls_verify": true,
  17. "tls_verify_depth": null,
  18. "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
  19. "enabled": true
  20. }

Update Or Create Service

Note: This API is not available in DB-less mode.

Create Or Update Service

/services/{service name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to create or update.
Create Or Update Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to create or update.
service name or id
required
The unique identifier or the name of the Service to create or update.
Create Or Update Service Associated to a Specific Route

/routes/{route name or id}/service

AttributesDescription
route name or id
required
The unique identifier or the name of the Route associated to the Service to be created or updated.
Create Or Update Service Associated to a Specific Plugin

/plugins/{plugin id}/service

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Service to be created or updated.

Request Body

AttributesDescription
name
optional
The Service name.
retries
optional
The number of retries to execute upon failure to proxy. Default: 5.
protocolThe protocol used to communicate with the upstream. Accepted values are: “grpc”, “grpcs”, “http”, “https”, “tcp”, “tls”, “tls_passthrough”, “udp”, “ws” , “wss” . Default: “http”.
hostThe host of the upstream server. Note that the host value is case sensitive.
portThe upstream server port. Default: 80.
path
optional
The path to be used in requests to the upstream server.
connect_timeout
optional
The timeout in milliseconds for establishing a connection to the upstream server. Default: 60000.
write_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: 60000.
read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: 60000.
tags
optional
An optional set of strings associated with the Service for grouping and filtering.
client_certificate
optional
Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is client_certificate.id=<client_certificate id>. With JSON, use ““client_certificate”:{“id”:”<client_certificate id>”}.
tls_verify
optional
Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.
tls_verify_depth
optional
Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected. Default: null.
ca_certificates
optional
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). 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.
enabledWhether 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. Default: true.
url
shorthand-attribute
Shorthand attribute to set protocol, host, port and path at once. This attribute is write-only (the Admin API never returns the URL).

Inserts (or replaces) the Service under the requested resource with the definition specified in the body. The Service will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the Service being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new Service 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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Service

Note: This API is not available in DB-less mode.

Delete Service

/services/{service name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to delete.
Delete Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to delete.
service name or id
required
The unique identifier or the name of the Service to delete.

Response

  1. HTTP 204 No Content

Route Object

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. Depending on the protocols configured to be matched by the Route (as defined with the protocols field), this means that at least one of the following attributes must be set:

  • For http, at least one of methods, hosts, headers or paths;
  • For https, at least one of methods, hosts, headers, paths or snis;
  • For tcp, at least one of sources or destinations;
  • For tls, at least one of sources, destinations or snis;
  • For tls_passthrough, set snis;
  • For grpc, at least one of hosts, headers or paths;
  • For grpcs, at least one of hosts, headers, paths or snis.
  • For ws, at least one of hosts, headers or paths;
  • For wss, at least one of hosts, headers, paths or snis;

A route can’t have both tls and tls_passthrough protocols at same time.

The 3.0.x release introduces a new router implementation: atc-router. The router adds:

  • Reduced router rebuild time when changing Kong Gateway’s configuration
  • Increased runtime performance when routing requests
  • Reduced P99 latency from 1.5s to 0.1s with 10,000 routes

Learn more about the router:

Path handling algorithms

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 not be configurable 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.

"v0" is the behavior used in Kong 0.x, 2.x and 3.x. It treats service.path, route.path and request path as segments of a URL. It will always join them via slashes. Given a service path /s, route path /r and request path /re, the concatenated path will be /s/re. If the resulting path is a single slash, no further transformation is done to it. If it’s longer, then the trailing slash is removed.

"v1" is the behavior used in Kong 1.x. It treats service.path as a prefix, and ignores the initial slashes of the request and route paths. Given service path /s, route path /r and request path /re, the concatenated path will be /sre.

Both versions of the algorithm detect “double slashes” when combining paths, replacing them by single slashes.

The following table shows the possible combinations of path handling version, strip path, and request:

service.pathroute.pathrequestroute.strip_pathroute.path_handlingrequest pathupstream path
/s/fv0reqfalsev0/fv0/req/s/fv0/req
/s/fv0blankfalsev0/fv0/s/fv0
/s/fv1reqfalsev1/fv1/req/sfv1/req
/s/fv1blankfalsev1/fv1/sfv1
/s/tv0reqtruev0/tv0/req/s/req
/s/tv0blanktruev0/tv0/s
/s/tv1reqtruev1/tv1/req/s/req
/s/tv1blanktruev1/tv1/s
/s/fv0/reqfalsev0/fv0/req/s/fv0/req
/s/fv0/blankfalsev0/fv0//s/fv01/
/s/fv1/reqfalsev1/fv1/req/sfv1/req
/s/fv1/blankfalsev1/fv1//sfv1/
/s/tv0/reqtruev0/tv0/req/s/req
/s/tv0/blanktruev0/tv0//s/
/s/tv1/reqtruev1/tv1/req/sreq
/s/tv1/blanktruev1/tv1//s

Routes can be both tagged and filtered by tags.

  1. {
  2. "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-route",
  6. "protocols": ["http", "https"],
  7. "methods": ["GET", "POST"],
  8. "hosts": ["example.com", "foo.test"],
  9. "paths": ["/foo", "/bar"],
  10. "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
  11. "https_redirect_status_code": 426,
  12. "regex_priority": 0,
  13. "strip_path": true,
  14. "path_handling": "v0",
  15. "preserve_host": false,
  16. "request_buffering": true,
  17. "response_buffering": true,
  18. "tags": ["user-level", "low-priority"],
  19. "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
  20. }

Add Route

Note: This API is not available in DB-less mode.

Create Route

/routes

Create Route Associated to a Specific Service

/services/{service name or id}/routes

AttributesDescription
service name or id
required
The unique identifier or the name attribute of the Service that should be associated to the newly-created Route.

Request Body

AttributesDescription
name
optional
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”.
protocolsAn array of the protocols this Route should allow. See the 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. Default: [“http”, “https”].
methods
semi-optional
A list of HTTP methods that match this Route.
hosts
semi-optional
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.
paths
semi-optional
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. The path patterns are matched against a normalized path, with most percent-encoded characters decoded, path folding, and preserved semantics. For more details read rfc3986.
headers
semi-optional
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.
https_redirect_status_codeThe 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. Accepted values are: 426, 301, 302, 307, 308. Default: 426. NOTE: This applies only if the route is only listening to the HTTPS protocol.
regex_priority
optional
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.
strip_pathWhen matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Default: true.
path_handling
optional
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. Accepted values are: “v0”, “v1”. Default: “v0”.
preserve_hostWhen 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.
request_bufferingWhether 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_bufferingWhether 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
semi-optional
A list of SNIs that match this Route when using stream routing.
sources
semi-optional
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”.
destinations
semi-optional
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”.
tags
optional
An optional set of strings associated with the Route for grouping and filtering.
service
optional
The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is service.id=<service id> or service.name=<service name>. With JSON, use ““service”:{“id”:”<service id>”} or “service”:{“name”:”<service name>”}.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-route",
  6. "protocols": ["http", "https"],
  7. "methods": ["GET", "POST"],
  8. "hosts": ["example.com", "foo.test"],
  9. "paths": ["/foo", "/bar"],
  10. "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
  11. "https_redirect_status_code": 426,
  12. "regex_priority": 0,
  13. "strip_path": true,
  14. "path_handling": "v0",
  15. "preserve_host": false,
  16. "request_buffering": true,
  17. "response_buffering": true,
  18. "tags": ["user-level", "low-priority"],
  19. "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
  20. }

List Routes

List All Routes

/routes

List Routes Associated to a Specific Service

/services/{service name or id}/routes

AttributesDescription
service name or id
required
The unique identifier or the name attribute of the Service whose Routes are to be retrieved. When using this endpoint, only Routes associated to the specified Service will be listed.

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "a9daa3ba-8186-4a0d-96e8-00d80ce7240b",
  4. "created_at": 1422386534,
  5. "updated_at": 1422386534,
  6. "name": "my-route",
  7. "protocols": ["http", "https"],
  8. "methods": ["GET", "POST"],
  9. "hosts": ["example.com", "foo.test"],
  10. "paths": ["/foo", "/bar"],
  11. "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
  12. "https_redirect_status_code": 426,
  13. "regex_priority": 0,
  14. "strip_path": true,
  15. "path_handling": "v0",
  16. "preserve_host": false,
  17. "request_buffering": true,
  18. "response_buffering": true,
  19. "tags": ["user-level", "low-priority"],
  20. "service": {"id":"127dfc88-ed57-45bf-b77a-a9d3a152ad31"}
  21. }, {
  22. "id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982",
  23. "created_at": 1422386534,
  24. "updated_at": 1422386534,
  25. "name": "my-route",
  26. "protocols": ["tcp", "tls"],
  27. "https_redirect_status_code": 426,
  28. "regex_priority": 0,
  29. "strip_path": true,
  30. "path_handling": "v0",
  31. "preserve_host": false,
  32. "request_buffering": true,
  33. "response_buffering": true,
  34. "snis": ["foo.test", "example.com"],
  35. "sources": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
  36. "destinations": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
  37. "tags": ["admin", "high-priority", "critical"],
  38. "service": {"id":"ba641b07-e74a-430a-ab46-94b61e5ea66b"}
  39. }],
  40. "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  41. }

Retrieve Route

Retrieve Route

/routes/{route name or id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to retrieve.
Retrieve Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to retrieve.
route name or id
required
The unique identifier or the name of the Route to retrieve.
Retrieve Route Associated to a Specific Plugin

/plugins/{plugin id}/route

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Route to be retrieved.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-route",
  6. "protocols": ["http", "https"],
  7. "methods": ["GET", "POST"],
  8. "hosts": ["example.com", "foo.test"],
  9. "paths": ["/foo", "/bar"],
  10. "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
  11. "https_redirect_status_code": 426,
  12. "regex_priority": 0,
  13. "strip_path": true,
  14. "path_handling": "v0",
  15. "preserve_host": false,
  16. "request_buffering": true,
  17. "response_buffering": true,
  18. "tags": ["user-level", "low-priority"],
  19. "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
  20. }

Update Route

Note: This API is not available in DB-less mode.

Update Route

/routes/{route name or id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to update.
Update Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to update.
route name or id
required
The unique identifier or the name of the Route to update.
Update Route Associated to a Specific Plugin

/plugins/{plugin id}/route

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Route to be updated.

Request Body

AttributesDescription
name
optional
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”.
protocolsAn array of the protocols this Route should allow. See the 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. Default: [“http”, “https”].
methods
semi-optional
A list of HTTP methods that match this Route.
hosts
semi-optional
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.
paths
semi-optional
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. The path patterns are matched against a normalized path, with most percent-encoded characters decoded, path folding, and preserved semantics. For more details read rfc3986.
headers
semi-optional
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.
https_redirect_status_codeThe 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. Accepted values are: 426, 301, 302, 307, 308. Default: 426. NOTE: This applies only if the route is only listening to the HTTPS protocol.
regex_priority
optional
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.
strip_pathWhen matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Default: true.
path_handling
optional
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. Accepted values are: “v0”, “v1”. Default: “v0”.
preserve_hostWhen 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.
request_bufferingWhether 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_bufferingWhether 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
semi-optional
A list of SNIs that match this Route when using stream routing.
sources
semi-optional
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”.
destinations
semi-optional
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”.
tags
optional
An optional set of strings associated with the Route for grouping and filtering.
service
optional
The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is service.id=<service id> or service.name=<service name>. With JSON, use ““service”:{“id”:”<service id>”} or “service”:{“name”:”<service name>”}.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
  3. "created_at": 1422386534,
  4. "updated_at": 1422386534,
  5. "name": "my-route",
  6. "protocols": ["http", "https"],
  7. "methods": ["GET", "POST"],
  8. "hosts": ["example.com", "foo.test"],
  9. "paths": ["/foo", "/bar"],
  10. "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
  11. "https_redirect_status_code": 426,
  12. "regex_priority": 0,
  13. "strip_path": true,
  14. "path_handling": "v0",
  15. "preserve_host": false,
  16. "request_buffering": true,
  17. "response_buffering": true,
  18. "tags": ["user-level", "low-priority"],
  19. "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
  20. }

Update Or Create Route

Note: This API is not available in DB-less mode.

Create Or Update Route

/routes/{route name or id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to create or update.
Create Or Update Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to create or update.
route name or id
required
The unique identifier or the name of the Route to create or update.
Create Or Update Route Associated to a Specific Plugin

/plugins/{plugin id}/route

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Route to be created or updated.

Request Body

AttributesDescription
name
optional
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”.
protocolsAn array of the protocols this Route should allow. See the 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. Default: [“http”, “https”].
methods
semi-optional
A list of HTTP methods that match this Route.
hosts
semi-optional
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.
paths
semi-optional
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. The path patterns are matched against a normalized path, with most percent-encoded characters decoded, path folding, and preserved semantics. For more details read rfc3986.
headers
semi-optional
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.
https_redirect_status_codeThe 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. Accepted values are: 426, 301, 302, 307, 308. Default: 426. NOTE: This applies only if the route is only listening to the HTTPS protocol.
regex_priority
optional
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.
strip_pathWhen matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Default: true.
path_handling
optional
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. Accepted values are: “v0”, “v1”. Default: “v0”.
preserve_hostWhen 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.
request_bufferingWhether 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_bufferingWhether 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
semi-optional
A list of SNIs that match this Route when using stream routing.
sources
semi-optional
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”.
destinations
semi-optional
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”.
tags
optional
An optional set of strings associated with the Route for grouping and filtering.
service
optional
The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is service.id=<service id> or service.name=<service name>. With JSON, use ““service”:{“id”:”<service id>”} or “service”:{“name”:”<service name>”}.

Inserts (or replaces) the Route under the requested resource with the definition specified in the body. The Route will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the Route being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new Route 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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Route

Note: This API is not available in DB-less mode.

Delete Route

/routes/{route name or id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to delete.
Delete Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to delete.
route name or id
required
The unique identifier or the name of the Route to delete.

Response

  1. HTTP 204 No Content

Consumer Object

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary data store, or you can map the consumer list with your database to keep consistency between Kong and your existing primary data store.

Consumers can be both tagged and filtered by tags.

  1. {
  2. "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3. "created_at": 1422386534,
  4. "username": "my-username",
  5. "custom_id": "my-custom-id",
  6. "tags": ["user-level", "low-priority"]
  7. }

Add Consumer

Note: This API is not available in DB-less mode.

Create Consumer

/consumers

Request Body

AttributesDescription
username
semi-optional
The unique username of the Consumer. You must send either this field or custom_id with the request.
custom_id
semi-optional
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
optional
An optional set of strings associated with the Consumer for grouping and filtering.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3. "created_at": 1422386534,
  4. "username": "my-username",
  5. "custom_id": "my-custom-id",
  6. "tags": ["user-level", "low-priority"]
  7. }

List Consumers

List All Consumers

/consumers

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7",
  4. "created_at": 1422386534,
  5. "username": "my-username",
  6. "custom_id": "my-custom-id",
  7. "tags": ["user-level", "low-priority"]
  8. }, {
  9. "id": "01c23299-839c-49a5-a6d5-8864c09184af",
  10. "created_at": 1422386534,
  11. "username": "my-username",
  12. "custom_id": "my-custom-id",
  13. "tags": ["admin", "high-priority", "critical"]
  14. }],
  15. "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  16. }

Retrieve Consumer

Retrieve Consumer

/consumers/{consumer username or id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to retrieve.
Retrieve Consumer Associated to a Specific Plugin

/plugins/{plugin id}/consumer

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Consumer to be retrieved.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3. "created_at": 1422386534,
  4. "username": "my-username",
  5. "custom_id": "my-custom-id",
  6. "tags": ["user-level", "low-priority"]
  7. }

Update Consumer

Note: This API is not available in DB-less mode.

Update Consumer

/consumers/{consumer username or id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to update.
Update Consumer Associated to a Specific Plugin

/plugins/{plugin id}/consumer

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Consumer to be updated.

Request Body

AttributesDescription
username
semi-optional
The unique username of the Consumer. You must send either this field or custom_id with the request.
custom_id
semi-optional
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
optional
An optional set of strings associated with the Consumer for grouping and filtering.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3. "created_at": 1422386534,
  4. "username": "my-username",
  5. "custom_id": "my-custom-id",
  6. "tags": ["user-level", "low-priority"]
  7. }

Update Or Create Consumer

Note: This API is not available in DB-less mode.

Create Or Update Consumer

/consumers/{consumer username or id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to create or update.
Create Or Update Consumer Associated to a Specific Plugin

/plugins/{plugin id}/consumer

AttributesDescription
plugin id
required
The unique identifier of the Plugin associated to the Consumer to be created or updated.

Request Body

AttributesDescription
username
semi-optional
The unique username of the Consumer. You must send either this field or custom_id with the request.
custom_id
semi-optional
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
optional
An optional set of strings associated with the Consumer for grouping and filtering.

Inserts (or replaces) the Consumer under the requested resource with the definition specified in the body. The Consumer will be identified via the username or id attribute.

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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Consumer

Note: This API is not available in DB-less mode.

Delete Consumer

/consumers/{consumer username or id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to delete.

Response

  1. HTTP 204 No Content

Plugin Object

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.

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.

Plugins can be both tagged and filtered by tags.

  1. {
  2. "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
  3. "name": "rate-limiting",
  4. "created_at": 1422386534,
  5. "route": null,
  6. "service": null,
  7. "consumer": null,
  8. "config": {"minute":20, "hour":500},
  9. "protocols": ["http", "https"],
  10. "enabled": true,
  11. "tags": ["user-level", "low-priority"],
  12. "ordering": {"before":["plugin-name"]}
  13. }

See the Precedence section below for more details.

Precedence

A plugin will always be run once and only once per request. But the configuration with which it will run depends on the entities it has been configured for.

Plugins can be configured for various entities, combination of entities, or even globally. This is useful, for example, when you wish to configure a plugin a certain way for most requests, but make authenticated requests behave slightly differently.

Therefore, there exists an order of precedence for running a plugin when it has been applied to different entities with different configurations. The rule of thumb is: the more specific a plugin is with regards to how many entities it has been configured on, the higher its priority.

The complete order of precedence when a plugin has been configured multiple times is:

  1. Plugins configured on a combination of: a Route, a Service, and a Consumer. (Consumer means the request must be authenticated).
  2. Plugins configured on a combination of a Route and a Consumer. (Consumer means the request must be authenticated).
  3. Plugins configured on a combination of a Service and a Consumer. (Consumer means the request must be authenticated).
  4. Plugins configured on a combination of a Route and a Service.
  5. Plugins configured on a Consumer. (Consumer means the request must be authenticated).
  6. Plugins configured on a Route.
  7. Plugins configured on a Service.
  8. Plugins configured to run globally.

Example: if the rate-limiting plugin is applied twice (with different configurations): for a Service (Plugin config A), and for a Consumer (Plugin config B), then requests authenticating this Consumer will run Plugin config B and ignore A. However, requests that do not authenticate this Consumer will fallback to running Plugin config A. Note that if config B is disabled (its enabled flag is set to false), config A will apply to requests that would have otherwise matched config B.

Add Plugin

Note: This API is not available in DB-less mode.

Create Plugin

/plugins

Create Plugin Associated to a Specific Route

/routes/{route name or id}/plugins

AttributesDescription
route name or id
required
The unique identifier or the name attribute of the Route that should be associated to the newly-created Plugin.
Create Plugin Associated to a Specific Service

/services/{service name or id}/plugins

AttributesDescription
service name or id
required
The unique identifier or the name attribute of the Service that should be associated to the newly-created Plugin.
Create Plugin Associated to a Specific Consumer

/consumers/{consumer name or id}/plugins

AttributesDescription
consumer name or id
required
The unique identifier or the name attribute of the Consumer that should be associated to the newly-created Plugin.

Request Body

AttributesDescription
nameThe name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.
route
optional
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=<route id> or route.name=<route name>. With JSON, use ““route”:{“id”:”<route id>”} or “route”:{“name”:”<route name>”}.
service
optional
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. Default: null.With form-encoded, the notation is service.id=<service id> or service.name=<service name>. With JSON, use ““service”:{“id”:”<service id>”} or “service”:{“name”:”<service name>”}.
consumer
optional
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. Default: null.With form-encoded, the notation is consumer.id=<consumer id> or consumer.username=<consumer username>. With JSON, use ““consumer”:{“id”:”<consumer id>”} or “consumer”:{“username”:”<consumer username>”}.
config
optional
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.
protocolsA 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”. Default: [“grpc”, “grpcs”, “http”, “https”].
enabledWhether the plugin is applied. Default: true.
tags
optional
An optional set of strings associated with the Plugin for grouping and filtering.
ordering
optional
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.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
  3. "name": "rate-limiting",
  4. "created_at": 1422386534,
  5. "route": null,
  6. "service": null,
  7. "consumer": null,
  8. "config": {"minute":20, "hour":500},
  9. "protocols": ["http", "https"],
  10. "enabled": true,
  11. "tags": ["user-level", "low-priority"],
  12. "ordering": {"before":["plugin-name"]}
  13. }

List Plugins

List All Plugins

/plugins

List Plugins Associated to a Specific Route

/routes/{route name or id}/plugins

AttributesDescription
route name or id
required
The unique identifier or the name attribute of the Route whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Route will be listed.
List Plugins Associated to a Specific Service

/services/{service name or id}/plugins

AttributesDescription
service name or id
required
The unique identifier or the name attribute of the Service whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Service will be listed.
List Plugins Associated to a Specific Consumer

/consumers/{consumer name or id}/plugins

AttributesDescription
consumer name or id
required
The unique identifier or the name attribute of the Consumer whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Consumer will be listed.

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "02621eee-8309-4bf6-b36b-a82017a5393e",
  4. "name": "rate-limiting",
  5. "created_at": 1422386534,
  6. "route": null,
  7. "service": null,
  8. "consumer": null,
  9. "config": {"minute":20, "hour":500},
  10. "protocols": ["http", "https"],
  11. "enabled": true,
  12. "tags": ["user-level", "low-priority"],
  13. "ordering": {"before":["plugin-name"]}
  14. }, {
  15. "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4",
  16. "name": "rate-limiting",
  17. "created_at": 1422386534,
  18. "route": null,
  19. "service": null,
  20. "consumer": null,
  21. "config": {"minute":20, "hour":500},
  22. "protocols": ["tcp", "tls"],
  23. "enabled": true,
  24. "tags": ["admin", "high-priority", "critical"],
  25. "ordering": {"after":["plugin-name"]}
  26. }],
  27. "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  28. }

Retrieve Plugin

Retrieve Plugin

/plugins/{plugin id}

AttributesDescription
plugin id
required
The unique identifier of the Plugin to retrieve.
Retrieve Plugin Associated to a Specific Route

/routes/{route name or id}/plugins/{plugin id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to retrieve.
plugin id
required
The unique identifier of the Plugin to retrieve.
Retrieve Plugin Associated to a Specific Service

/services/{service name or id}/plugins/{plugin id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to retrieve.
plugin id
required
The unique identifier of the Plugin to retrieve.
Retrieve Plugin Associated to a Specific Consumer

/consumers/{consumer username or id}/plugins/{plugin id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to retrieve.
plugin id
required
The unique identifier of the Plugin to retrieve.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
  3. "name": "rate-limiting",
  4. "created_at": 1422386534,
  5. "route": null,
  6. "service": null,
  7. "consumer": null,
  8. "config": {"minute":20, "hour":500},
  9. "protocols": ["http", "https"],
  10. "enabled": true,
  11. "tags": ["user-level", "low-priority"],
  12. "ordering": {"before":["plugin-name"]}
  13. }

Update Plugin

Note: This API is not available in DB-less mode.

Update Plugin

/plugins/{plugin id}

AttributesDescription
plugin id
required
The unique identifier of the Plugin to update.
Update Plugin Associated to a Specific Route

/routes/{route name or id}/plugins/{plugin id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to update.
plugin id
required
The unique identifier of the Plugin to update.
Update Plugin Associated to a Specific Service

/services/{service name or id}/plugins/{plugin id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to update.
plugin id
required
The unique identifier of the Plugin to update.
Update Plugin Associated to a Specific Consumer

/consumers/{consumer username or id}/plugins/{plugin id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to update.
plugin id
required
The unique identifier of the Plugin to update.

Request Body

AttributesDescription
nameThe name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.
route
optional
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=<route id> or route.name=<route name>. With JSON, use ““route”:{“id”:”<route id>”} or “route”:{“name”:”<route name>”}.
service
optional
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. Default: null.With form-encoded, the notation is service.id=<service id> or service.name=<service name>. With JSON, use ““service”:{“id”:”<service id>”} or “service”:{“name”:”<service name>”}.
consumer
optional
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. Default: null.With form-encoded, the notation is consumer.id=<consumer id> or consumer.username=<consumer username>. With JSON, use ““consumer”:{“id”:”<consumer id>”} or “consumer”:{“username”:”<consumer username>”}.
config
optional
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.
protocolsA 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”. Default: [“grpc”, “grpcs”, “http”, “https”].
enabledWhether the plugin is applied. Default: true.
tags
optional
An optional set of strings associated with the Plugin for grouping and filtering.
ordering
optional
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.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
  3. "name": "rate-limiting",
  4. "created_at": 1422386534,
  5. "route": null,
  6. "service": null,
  7. "consumer": null,
  8. "config": {"minute":20, "hour":500},
  9. "protocols": ["http", "https"],
  10. "enabled": true,
  11. "tags": ["user-level", "low-priority"],
  12. "ordering": {"before":["plugin-name"]}
  13. }

Update Or Create Plugin

Note: This API is not available in DB-less mode.

Create Or Update Plugin

/plugins/{plugin id}

AttributesDescription
plugin id
required
The unique identifier of the Plugin to create or update.
Create Or Update Plugin Associated to a Specific Route

/routes/{route name or id}/plugins/{plugin id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to create or update.
plugin id
required
The unique identifier of the Plugin to create or update.
Create Or Update Plugin Associated to a Specific Service

/services/{service name or id}/plugins/{plugin id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to create or update.
plugin id
required
The unique identifier of the Plugin to create or update.
Create Or Update Plugin Associated to a Specific Consumer

/consumers/{consumer username or id}/plugins/{plugin id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to create or update.
plugin id
required
The unique identifier of the Plugin to create or update.

Request Body

AttributesDescription
nameThe name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.
route
optional
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=<route id> or route.name=<route name>. With JSON, use ““route”:{“id”:”<route id>”} or “route”:{“name”:”<route name>”}.
service
optional
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. Default: null.With form-encoded, the notation is service.id=<service id> or service.name=<service name>. With JSON, use ““service”:{“id”:”<service id>”} or “service”:{“name”:”<service name>”}.
consumer
optional
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. Default: null.With form-encoded, the notation is consumer.id=<consumer id> or consumer.username=<consumer username>. With JSON, use ““consumer”:{“id”:”<consumer id>”} or “consumer”:{“username”:”<consumer username>”}.
config
optional
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.
protocolsA 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”. Default: [“grpc”, “grpcs”, “http”, “https”].
enabledWhether the plugin is applied. Default: true.
tags
optional
An optional set of strings associated with the Plugin for grouping and filtering.
ordering
optional
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.

Inserts (or replaces) the Plugin under the requested resource with the definition specified in the body. The Plugin will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the Plugin being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new Plugin 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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Plugin

Note: This API is not available in DB-less mode.

Delete Plugin

/plugins/{plugin id}

AttributesDescription
plugin id
required
The unique identifier of the Plugin to delete.
Delete Plugin Associated to a Specific Route

/routes/{route name or id}/plugins/{plugin id}

AttributesDescription
route name or id
required
The unique identifier or the name of the Route to delete.
plugin id
required
The unique identifier of the Plugin to delete.
Delete Plugin Associated to a Specific Service

/services/{service name or id}/plugins/{plugin id}

AttributesDescription
service name or id
required
The unique identifier or the name of the Service to delete.
plugin id
required
The unique identifier of the Plugin to delete.
Delete Plugin Associated to a Specific Consumer

/consumers/{consumer username or id}/plugins/{plugin id}

AttributesDescription
consumer username or id
required
The unique identifier or the username of the Consumer to delete.
plugin id
required
The unique identifier of the Plugin to delete.

Response

  1. HTTP 204 No Content

Retrieve Enabled Plugins

Retrieve a list of all installed plugins on the Kong node.

/plugins/enabled

Response

  1. HTTP 200 OK
  1. {
  2. "enabled_plugins": [
  3. "jwt",
  4. "acl",
  5. "cors",
  6. "oauth2",
  7. "tcp-log",
  8. "udp-log",
  9. "file-log",
  10. "http-log",
  11. "key-auth",
  12. "hmac-auth",
  13. "basic-auth",
  14. "ip-restriction",
  15. "request-transformer",
  16. "response-transformer",
  17. "request-size-limiting",
  18. "rate-limiting",
  19. "response-ratelimiting",
  20. "aws-lambda",
  21. "bot-detection",
  22. "correlation-id",
  23. "datadog",
  24. "galileo",
  25. "ldap-auth",
  26. "loggly",
  27. "statsd",
  28. "syslog"
  29. ]
  30. }

Certificate Object

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.

Certificates can be both tagged and filtered by tags.

  1. {
  2. "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "key": "-----BEGIN RSA PRIVATE KEY-----...",
  6. "cert_alt": "-----BEGIN CERTIFICATE-----...",
  7. "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
  8. "tags": ["user-level", "low-priority"]
  9. }

Add Certificate

Note: This API is not available in DB-less mode.

Create Certificate

/certificates

Request Body

AttributesDescription
certPEM-encoded public certificate chain of the SSL key pair. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
keyPEM-encoded private key of the SSL key pair. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
cert_alt
optional
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 in a vault. References must follow a specific format.
key_alt
optional
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 in a vault. References must follow a specific format.
tags
optional
An optional set of strings associated with the Certificate for grouping and filtering.
snis
shorthand-attribute
An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "key": "-----BEGIN RSA PRIVATE KEY-----...",
  6. "cert_alt": "-----BEGIN CERTIFICATE-----...",
  7. "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
  8. "tags": ["user-level", "low-priority"]
  9. }

List Certificates

List All Certificates

/certificates

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6",
  4. "created_at": 1422386534,
  5. "cert": "-----BEGIN CERTIFICATE-----...",
  6. "key": "-----BEGIN RSA PRIVATE KEY-----...",
  7. "cert_alt": "-----BEGIN CERTIFICATE-----...",
  8. "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
  9. "tags": ["user-level", "low-priority"]
  10. }, {
  11. "id": "a9b2107f-a214-47b3-add4-46b942187924",
  12. "created_at": 1422386534,
  13. "cert": "-----BEGIN CERTIFICATE-----...",
  14. "key": "-----BEGIN RSA PRIVATE KEY-----...",
  15. "cert_alt": "-----BEGIN CERTIFICATE-----...",
  16. "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
  17. "tags": ["admin", "high-priority", "critical"]
  18. }],
  19. "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  20. }

Retrieve Certificate

Retrieve Certificate

/certificates/{certificate id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to retrieve.
Retrieve Certificate Associated to a Specific Upstream

/upstreams/{upstream name or id}/client_certificate

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream associated to the Certificate to be retrieved.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "key": "-----BEGIN RSA PRIVATE KEY-----...",
  6. "cert_alt": "-----BEGIN CERTIFICATE-----...",
  7. "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
  8. "tags": ["user-level", "low-priority"]
  9. }

Update Certificate

Note: This API is not available in DB-less mode.

Update Certificate

/certificates/{certificate id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to update.
Update Certificate Associated to a Specific Upstream

/upstreams/{upstream name or id}/client_certificate

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream associated to the Certificate to be updated.

Request Body

AttributesDescription
certPEM-encoded public certificate chain of the SSL key pair. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
keyPEM-encoded private key of the SSL key pair. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
cert_alt
optional
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 in a vault. References must follow a specific format.
key_alt
optional
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 in a vault. References must follow a specific format.
tags
optional
An optional set of strings associated with the Certificate for grouping and filtering.
snis
shorthand-attribute
An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "key": "-----BEGIN RSA PRIVATE KEY-----...",
  6. "cert_alt": "-----BEGIN CERTIFICATE-----...",
  7. "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
  8. "tags": ["user-level", "low-priority"]
  9. }

Update Or Create Certificate

Note: This API is not available in DB-less mode.

Create Or Update Certificate

/certificates/{certificate id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to create or update.
Create Or Update Certificate Associated to a Specific Upstream

/upstreams/{upstream name or id}/client_certificate

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream associated to the Certificate to be created or updated.

Request Body

AttributesDescription
certPEM-encoded public certificate chain of the SSL key pair. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
keyPEM-encoded private key of the SSL key pair. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
cert_alt
optional
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 in a vault. References must follow a specific format.
key_alt
optional
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 in a vault. References must follow a specific format.
tags
optional
An optional set of strings associated with the Certificate for grouping and filtering.
snis
shorthand-attribute
An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it.

Inserts (or replaces) the Certificate under the requested resource with the definition specified in the body. The Certificate will be identified via the name or id attribute.

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 its name.

When creating a new Certificate 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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Certificate

Note: This API is not available in DB-less mode.

Delete Certificate

/certificates/{certificate id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to delete.
Delete Certificate Associated to a Specific Upstream

/upstreams/{upstream name or id}/client_certificate

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream associated to the Certificate to be deleted.

Response

  1. HTTP 204 No Content

CA Certificate Object

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.

  1. {
  2. "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
  6. "tags": ["user-level", "low-priority"]
  7. }

Add CA Certificate

Note: This API is not available in DB-less mode.

Create CA Certificate

/ca_certificates

Request Body

AttributesDescription
certPEM-encoded public certificate of the CA.
cert_digest
optional
SHA256 hex digest of the public certificate.
tags
optional
An optional set of strings associated with the Certificate for grouping and filtering.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
  6. "tags": ["user-level", "low-priority"]
  7. }

List CA Certificates

List All CA Certificates

/ca_certificates

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "43429efd-b3a5-4048-94cb-5cc4029909bb",
  4. "created_at": 1422386534,
  5. "cert": "-----BEGIN CERTIFICATE-----...",
  6. "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
  7. "tags": ["user-level", "low-priority"]
  8. }, {
  9. "id": "d26761d5-83a4-4f24-ac6c-cff276f2b79c",
  10. "created_at": 1422386534,
  11. "cert": "-----BEGIN CERTIFICATE-----...",
  12. "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
  13. "tags": ["admin", "high-priority", "critical"]
  14. }],
  15. "next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  16. }

Retrieve CA Certificate

Retrieve CA Certificate

/ca_certificates/{ca_certificate id}

AttributesDescription
ca_certificate id
required
The unique identifier of the CA Certificate to retrieve.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
  6. "tags": ["user-level", "low-priority"]
  7. }

Update CA Certificate

Note: This API is not available in DB-less mode.

Update CA Certificate

/ca_certificates/{ca_certificate id}

AttributesDescription
ca_certificate id
required
The unique identifier of the CA Certificate to update.

Request Body

AttributesDescription
certPEM-encoded public certificate of the CA.
cert_digest
optional
SHA256 hex digest of the public certificate.
tags
optional
An optional set of strings associated with the Certificate for grouping and filtering.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
  3. "created_at": 1422386534,
  4. "cert": "-----BEGIN CERTIFICATE-----...",
  5. "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
  6. "tags": ["user-level", "low-priority"]
  7. }

Update Or Create CA Certificate

Note: This API is not available in DB-less mode.

Create Or Update CA Certificate

/ca_certificates/{ca_certificate id}

AttributesDescription
ca_certificate id
required
The unique identifier of the CA Certificate to create or update.

Request Body

AttributesDescription
certPEM-encoded public certificate of the CA.
cert_digest
optional
SHA256 hex digest of the public certificate.
tags
optional
An optional set of strings associated with the Certificate for grouping and filtering.

Inserts (or replaces) the CA Certificate under the requested resource with the definition specified in the body. The CA Certificate will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the CA Certificate being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new CA Certificate 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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete CA Certificate

Note: This API is not available in DB-less mode.

Delete CA Certificate

/ca_certificates/{ca_certificate id}

AttributesDescription
ca_certificate id
required
The unique identifier of the CA Certificate to delete.

Response

  1. HTTP 204 No Content

SNI Object

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.

SNIs can be both tagged and filtered by tags.

  1. {
  2. "id": "91020192-062d-416f-a275-9addeeaffaf2",
  3. "name": "my-sni",
  4. "created_at": 1422386534,
  5. "tags": ["user-level", "low-priority"],
  6. "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
  7. }

Add SNI

Note: This API is not available in DB-less mode.

Create SNI

/snis

Create SNI Associated to a Specific Certificate

/certificates/{certificate name or id}/snis

AttributesDescription
certificate name or id
required
The unique identifier or the name attribute of the Certificate that should be associated to the newly-created SNI.

Request Body

AttributesDescription
nameThe SNI name to associate with the given certificate.
tags
optional
An optional set of strings associated with the SNIs for grouping and filtering.
certificateThe 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=<certificate id>. With JSON, use ““certificate”:{“id”:”<certificate id>”}.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "91020192-062d-416f-a275-9addeeaffaf2",
  3. "name": "my-sni",
  4. "created_at": 1422386534,
  5. "tags": ["user-level", "low-priority"],
  6. "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
  7. }

List SNIs

List All SNIs

/snis

List SNIs Associated to a Specific Certificate

/certificates/{certificate name or id}/snis

AttributesDescription
certificate name or id
required
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.

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "147f5ef0-1ed6-4711-b77f-489262f8bff7",
  4. "name": "my-sni",
  5. "created_at": 1422386534,
  6. "tags": ["user-level", "low-priority"],
  7. "certificate": {"id":"a3ad71a8-6685-4b03-a101-980a953544f6"}
  8. }, {
  9. "id": "b87eb55d-69a1-41d2-8653-8d706eecefc0",
  10. "name": "my-sni",
  11. "created_at": 1422386534,
  12. "tags": ["admin", "high-priority", "critical"],
  13. "certificate": {"id":"4e8d95d4-40f2-4818-adcb-30e00c349618"}
  14. }],
  15. "next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  16. }

Retrieve SNI

Retrieve SNI

/snis/{sni name or id}

AttributesDescription
sni name or id
required
The unique identifier or the name of the SNI to retrieve.
Retrieve SNI Associated to a Specific Certificate

/certificates/{certificate id}/snis/{sni name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to retrieve.
sni name or id
required
The unique identifier or the name of the SNI to retrieve.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "91020192-062d-416f-a275-9addeeaffaf2",
  3. "name": "my-sni",
  4. "created_at": 1422386534,
  5. "tags": ["user-level", "low-priority"],
  6. "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
  7. }

Update SNI

Note: This API is not available in DB-less mode.

Update SNI

/snis/{sni name or id}

AttributesDescription
sni name or id
required
The unique identifier or the name of the SNI to update.
Update SNI Associated to a Specific Certificate

/certificates/{certificate id}/snis/{sni name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to update.
sni name or id
required
The unique identifier or the name of the SNI to update.

Request Body

AttributesDescription
nameThe SNI name to associate with the given certificate.
tags
optional
An optional set of strings associated with the SNIs for grouping and filtering.
certificateThe 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=<certificate id>. With JSON, use ““certificate”:{“id”:”<certificate id>”}.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "91020192-062d-416f-a275-9addeeaffaf2",
  3. "name": "my-sni",
  4. "created_at": 1422386534,
  5. "tags": ["user-level", "low-priority"],
  6. "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
  7. }

Update Or Create SNI

Note: This API is not available in DB-less mode.

Create Or Update SNI

/snis/{sni name or id}

AttributesDescription
sni name or id
required
The unique identifier or the name of the SNI to create or update.
Create Or Update SNI Associated to a Specific Certificate

/certificates/{certificate id}/snis/{sni name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to create or update.
sni name or id
required
The unique identifier or the name of the SNI to create or update.

Request Body

AttributesDescription
nameThe SNI name to associate with the given certificate.
tags
optional
An optional set of strings associated with the SNIs for grouping and filtering.
certificateThe 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=<certificate id>. With JSON, use ““certificate”:{“id”:”<certificate id>”}.

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.

Notice that specifying a name in the URL and a different one in the request body is not allowed.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete SNI

Note: This API is not available in DB-less mode.

Delete SNI

/snis/{sni name or id}

AttributesDescription
sni name or id
required
The unique identifier or the name of the SNI to delete.
Delete SNI Associated to a Specific Certificate

/certificates/{certificate id}/snis/{sni name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to delete.
sni name or id
required
The unique identifier or the name of the SNI to delete.

Response

  1. HTTP 204 No Content

Upstream Object

The upstream object represents a virtual hostname and can be used to load balance 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, 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.

Upstreams can be both tagged and filtered by tags.

  1. {
  2. "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
  3. "created_at": 1422386534,
  4. "name": "my-upstream",
  5. "algorithm": "round-robin",
  6. "hash_on": "none",
  7. "hash_fallback": "none",
  8. "hash_on_cookie_path": "/",
  9. "slots": 10000,
  10. "healthchecks": {
  11. "active": {
  12. "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
  13. "https_sni": "example.com",
  14. "https_verify_certificate": true,
  15. "healthy": {
  16. "interval": 0,
  17. "http_statuses": [200, 302],
  18. "successes": 0
  19. },
  20. "unhealthy": {
  21. "tcp_failures": 0,
  22. "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
  23. "http_failures": 0,
  24. "interval": 0,
  25. "timeouts": 0
  26. },
  27. "http_path": "/",
  28. "concurrency": 10,
  29. "timeout": 1,
  30. "type": "http"
  31. },
  32. "passive": {
  33. "healthy": {
  34. "successes": 0,
  35. "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
  36. },
  37. "unhealthy": {
  38. "tcp_failures": 0,
  39. "http_statuses": [429, 500, 503],
  40. "http_failures": 0,
  41. "timeouts": 0
  42. },
  43. "type": "http"
  44. },
  45. "threshold": 0
  46. },
  47. "tags": ["user-level", "low-priority"],
  48. "host_header": "example.com",
  49. "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
  50. }

Add Upstream

Note: This API is not available in DB-less mode.

Create Upstream

/upstreams

Create Upstream Associated to a Specific Certificate

/certificates/{certificate name or id}/upstreams

AttributesDescription
certificate name or id
required
The unique identifier or the name attribute of the Certificate that should be associated to the newly-created Upstream.

Request Body

AttributesDescription
nameThis is a hostname, which must be equal to the host of a Service.
algorithm
optional
Which load balancing algorithm to use. Accepted values are: “consistent-hashing”, “least-connections”, “round-robin”. Default: “round-robin”.
hash_on
optional
What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”. Default: “none”.
hash_fallback
optional
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. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”. Default: “none”.
hash_on_header
semi-optional
The header name to take the value from as hash input. Only required when hash_on is set to header.
hash_fallback_header
semi-optional
The header name to take the value from as hash input. Only required when hash_fallback is set to header.
hash_on_cookie
semi-optional
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.
hash_on_cookie_path
semi-optional
The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie. Default: “/“.
hash_on_query_arg
semi-optional
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.
hash_fallback_query_arg
semi-optional
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.
hash_on_uri_capture
semi-optional
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.
hash_fallback_uri_capture
semi-optional
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.
slots
optional
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. Default: 10000.
healthchecks.active.headers
optional
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.
healthchecks.active.https_sni
optional
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.
healthchecks.active.https_verify_certificateWhether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Default: true.
healthchecks.active.healthy.interval
optional
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.
healthchecks.active.healthy.http_statuses
optional
An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: [200, 302]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=302. With JSON, use an Array.
healthchecks.active.healthy.successes
optional
Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy. Default: 0.
healthchecks.active.unhealthy.tcp_failures
optional
Number of TCP failures in active probes to consider a target unhealthy. Default: 0.
healthchecks.active.unhealthy.http_statuses
optional
An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: [429, 404, 500, 501, 502, 503, 504, 505]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=404. With JSON, use an Array.
healthchecks.active.unhealthy.http_failures
optional
Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy. Default: 0.
healthchecks.active.unhealthy.interval
optional
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.
healthchecks.active.unhealthy.timeouts
optional
Number of timeouts in active probes to consider a target unhealthy. Default: 0.
healthchecks.active.http_path
optional
Path to use in GET HTTP request to run as a probe on active health checks. Default: “/“.
healthchecks.active.concurrency
optional
Number of targets to check concurrently in active health checks. Default: 10.
healthchecks.active.timeout
optional
Socket timeout for active health checks (in seconds). Default: 1.
healthchecks.active.type
optional
Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: “tcp”, “http”, “https”, “grpc”, “grpcs”. Default: “http”.
healthchecks.passive.healthy.successes
optional
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.
healthchecks.passive.healthy.http_statuses
optional
An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=201. With JSON, use an Array.
healthchecks.passive.unhealthy.tcp_failures
optional
Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: 0.
healthchecks.passive.unhealthy.http_statuses
optional
An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: [429, 500, 503]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=500. With JSON, use an Array.
healthchecks.passive.unhealthy.http_failures
optional
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.
healthchecks.passive.unhealthy.timeouts
optional
Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: 0.
healthchecks.passive.type
optional
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”.
healthchecks.threshold
optional
The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Default: 0.
tags
optional
An optional set of strings associated with the Upstream for grouping and filtering.
host_header
optional
The hostname to be used as Host header when proxying requests through Kong.
client_certificate
optional
If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is client_certificate.id=<client_certificate id>. With JSON, use ““client_certificate”:{“id”:”<client_certificate id>”}.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
  3. "created_at": 1422386534,
  4. "name": "my-upstream",
  5. "algorithm": "round-robin",
  6. "hash_on": "none",
  7. "hash_fallback": "none",
  8. "hash_on_cookie_path": "/",
  9. "slots": 10000,
  10. "healthchecks": {
  11. "active": {
  12. "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
  13. "https_sni": "example.com",
  14. "https_verify_certificate": true,
  15. "healthy": {
  16. "interval": 0,
  17. "http_statuses": [200, 302],
  18. "successes": 0
  19. },
  20. "unhealthy": {
  21. "tcp_failures": 0,
  22. "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
  23. "http_failures": 0,
  24. "interval": 0,
  25. "timeouts": 0
  26. },
  27. "http_path": "/",
  28. "concurrency": 10,
  29. "timeout": 1,
  30. "type": "http"
  31. },
  32. "passive": {
  33. "healthy": {
  34. "successes": 0,
  35. "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
  36. },
  37. "unhealthy": {
  38. "tcp_failures": 0,
  39. "http_statuses": [429, 500, 503],
  40. "http_failures": 0,
  41. "timeouts": 0
  42. },
  43. "type": "http"
  44. },
  45. "threshold": 0
  46. },
  47. "tags": ["user-level", "low-priority"],
  48. "host_header": "example.com",
  49. "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
  50. }

List Upstreams

List All Upstreams

/upstreams

List Upstreams Associated to a Specific Certificate

/certificates/{certificate name or id}/upstreams

AttributesDescription
certificate name or id
required
The unique identifier or the name attribute of the Certificate whose Upstreams are to be retrieved. When using this endpoint, only Upstreams associated to the specified Certificate will be listed.

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "4fe14415-73d5-4f00-9fbc-c72a0fccfcb2",
  4. "created_at": 1422386534,
  5. "name": "my-upstream",
  6. "algorithm": "round-robin",
  7. "hash_on": "none",
  8. "hash_fallback": "none",
  9. "hash_on_cookie_path": "/",
  10. "slots": 10000,
  11. "healthchecks": {
  12. "active": {
  13. "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
  14. "https_sni": "example.com",
  15. "https_verify_certificate": true,
  16. "healthy": {
  17. "interval": 0,
  18. "http_statuses": [200, 302],
  19. "successes": 0
  20. },
  21. "unhealthy": {
  22. "tcp_failures": 0,
  23. "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
  24. "http_failures": 0,
  25. "interval": 0,
  26. "timeouts": 0
  27. },
  28. "http_path": "/",
  29. "concurrency": 10,
  30. "timeout": 1,
  31. "type": "http"
  32. },
  33. "passive": {
  34. "healthy": {
  35. "successes": 0,
  36. "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
  37. },
  38. "unhealthy": {
  39. "tcp_failures": 0,
  40. "http_statuses": [429, 500, 503],
  41. "http_failures": 0,
  42. "timeouts": 0
  43. },
  44. "type": "http"
  45. },
  46. "threshold": 0
  47. },
  48. "tags": ["user-level", "low-priority"],
  49. "host_header": "example.com",
  50. "client_certificate": {"id":"a3395f66-2af6-4c79-bea2-1b6933764f80"}
  51. }, {
  52. "id": "885a0392-ef1b-4de3-aacf-af3f1697ce2c",
  53. "created_at": 1422386534,
  54. "name": "my-upstream",
  55. "algorithm": "round-robin",
  56. "hash_on": "none",
  57. "hash_fallback": "none",
  58. "hash_on_cookie_path": "/",
  59. "slots": 10000,
  60. "healthchecks": {
  61. "active": {
  62. "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
  63. "https_sni": "example.com",
  64. "https_verify_certificate": true,
  65. "healthy": {
  66. "interval": 0,
  67. "http_statuses": [200, 302],
  68. "successes": 0
  69. },
  70. "unhealthy": {
  71. "tcp_failures": 0,
  72. "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
  73. "http_failures": 0,
  74. "interval": 0,
  75. "timeouts": 0
  76. },
  77. "http_path": "/",
  78. "concurrency": 10,
  79. "timeout": 1,
  80. "type": "http"
  81. },
  82. "passive": {
  83. "healthy": {
  84. "successes": 0,
  85. "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
  86. },
  87. "unhealthy": {
  88. "tcp_failures": 0,
  89. "http_statuses": [429, 500, 503],
  90. "http_failures": 0,
  91. "timeouts": 0
  92. },
  93. "type": "http"
  94. },
  95. "threshold": 0
  96. },
  97. "tags": ["admin", "high-priority", "critical"],
  98. "host_header": "example.com",
  99. "client_certificate": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"}
  100. }],
  101. "next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  102. }

Retrieve Upstream

Retrieve Upstream

/upstreams/{upstream name or id}

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream to retrieve.
Retrieve Upstream Associated to a Specific Certificate

/certificates/{certificate id}/upstreams/{upstream name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to retrieve.
upstream name or id
required
The unique identifier or the name of the Upstream to retrieve.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
  3. "created_at": 1422386534,
  4. "name": "my-upstream",
  5. "algorithm": "round-robin",
  6. "hash_on": "none",
  7. "hash_fallback": "none",
  8. "hash_on_cookie_path": "/",
  9. "slots": 10000,
  10. "healthchecks": {
  11. "active": {
  12. "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
  13. "https_sni": "example.com",
  14. "https_verify_certificate": true,
  15. "healthy": {
  16. "interval": 0,
  17. "http_statuses": [200, 302],
  18. "successes": 0
  19. },
  20. "unhealthy": {
  21. "tcp_failures": 0,
  22. "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
  23. "http_failures": 0,
  24. "interval": 0,
  25. "timeouts": 0
  26. },
  27. "http_path": "/",
  28. "concurrency": 10,
  29. "timeout": 1,
  30. "type": "http"
  31. },
  32. "passive": {
  33. "healthy": {
  34. "successes": 0,
  35. "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
  36. },
  37. "unhealthy": {
  38. "tcp_failures": 0,
  39. "http_statuses": [429, 500, 503],
  40. "http_failures": 0,
  41. "timeouts": 0
  42. },
  43. "type": "http"
  44. },
  45. "threshold": 0
  46. },
  47. "tags": ["user-level", "low-priority"],
  48. "host_header": "example.com",
  49. "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
  50. }

Update Upstream

Note: This API is not available in DB-less mode.

Update Upstream

/upstreams/{upstream name or id}

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream to update.
Update Upstream Associated to a Specific Certificate

/certificates/{certificate id}/upstreams/{upstream name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to update.
upstream name or id
required
The unique identifier or the name of the Upstream to update.

Request Body

AttributesDescription
nameThis is a hostname, which must be equal to the host of a Service.
algorithm
optional
Which load balancing algorithm to use. Accepted values are: “consistent-hashing”, “least-connections”, “round-robin”. Default: “round-robin”.
hash_on
optional
What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”. Default: “none”.
hash_fallback
optional
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. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”. Default: “none”.
hash_on_header
semi-optional
The header name to take the value from as hash input. Only required when hash_on is set to header.
hash_fallback_header
semi-optional
The header name to take the value from as hash input. Only required when hash_fallback is set to header.
hash_on_cookie
semi-optional
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.
hash_on_cookie_path
semi-optional
The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie. Default: “/“.
hash_on_query_arg
semi-optional
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.
hash_fallback_query_arg
semi-optional
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.
hash_on_uri_capture
semi-optional
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.
hash_fallback_uri_capture
semi-optional
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.
slots
optional
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. Default: 10000.
healthchecks.active.headers
optional
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.
healthchecks.active.https_sni
optional
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.
healthchecks.active.https_verify_certificateWhether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Default: true.
healthchecks.active.healthy.interval
optional
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.
healthchecks.active.healthy.http_statuses
optional
An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: [200, 302]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=302. With JSON, use an Array.
healthchecks.active.healthy.successes
optional
Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy. Default: 0.
healthchecks.active.unhealthy.tcp_failures
optional
Number of TCP failures in active probes to consider a target unhealthy. Default: 0.
healthchecks.active.unhealthy.http_statuses
optional
An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: [429, 404, 500, 501, 502, 503, 504, 505]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=404. With JSON, use an Array.
healthchecks.active.unhealthy.http_failures
optional
Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy. Default: 0.
healthchecks.active.unhealthy.interval
optional
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.
healthchecks.active.unhealthy.timeouts
optional
Number of timeouts in active probes to consider a target unhealthy. Default: 0.
healthchecks.active.http_path
optional
Path to use in GET HTTP request to run as a probe on active health checks. Default: “/“.
healthchecks.active.concurrency
optional
Number of targets to check concurrently in active health checks. Default: 10.
healthchecks.active.timeout
optional
Socket timeout for active health checks (in seconds). Default: 1.
healthchecks.active.type
optional
Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: “tcp”, “http”, “https”, “grpc”, “grpcs”. Default: “http”.
healthchecks.passive.healthy.successes
optional
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.
healthchecks.passive.healthy.http_statuses
optional
An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=201. With JSON, use an Array.
healthchecks.passive.unhealthy.tcp_failures
optional
Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: 0.
healthchecks.passive.unhealthy.http_statuses
optional
An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: [429, 500, 503]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=500. With JSON, use an Array.
healthchecks.passive.unhealthy.http_failures
optional
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.
healthchecks.passive.unhealthy.timeouts
optional
Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: 0.
healthchecks.passive.type
optional
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”.
healthchecks.threshold
optional
The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Default: 0.
tags
optional
An optional set of strings associated with the Upstream for grouping and filtering.
host_header
optional
The hostname to be used as Host header when proxying requests through Kong.
client_certificate
optional
If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is client_certificate.id=<client_certificate id>. With JSON, use ““client_certificate”:{“id”:”<client_certificate id>”}.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
  3. "created_at": 1422386534,
  4. "name": "my-upstream",
  5. "algorithm": "round-robin",
  6. "hash_on": "none",
  7. "hash_fallback": "none",
  8. "hash_on_cookie_path": "/",
  9. "slots": 10000,
  10. "healthchecks": {
  11. "active": {
  12. "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
  13. "https_sni": "example.com",
  14. "https_verify_certificate": true,
  15. "healthy": {
  16. "interval": 0,
  17. "http_statuses": [200, 302],
  18. "successes": 0
  19. },
  20. "unhealthy": {
  21. "tcp_failures": 0,
  22. "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
  23. "http_failures": 0,
  24. "interval": 0,
  25. "timeouts": 0
  26. },
  27. "http_path": "/",
  28. "concurrency": 10,
  29. "timeout": 1,
  30. "type": "http"
  31. },
  32. "passive": {
  33. "healthy": {
  34. "successes": 0,
  35. "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
  36. },
  37. "unhealthy": {
  38. "tcp_failures": 0,
  39. "http_statuses": [429, 500, 503],
  40. "http_failures": 0,
  41. "timeouts": 0
  42. },
  43. "type": "http"
  44. },
  45. "threshold": 0
  46. },
  47. "tags": ["user-level", "low-priority"],
  48. "host_header": "example.com",
  49. "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
  50. }

Update Or Create Upstream

Note: This API is not available in DB-less mode.

Create Or Update Upstream

/upstreams/{upstream name or id}

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream to create or update.
Create Or Update Upstream Associated to a Specific Certificate

/certificates/{certificate id}/upstreams/{upstream name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to create or update.
upstream name or id
required
The unique identifier or the name of the Upstream to create or update.

Request Body

AttributesDescription
nameThis is a hostname, which must be equal to the host of a Service.
algorithm
optional
Which load balancing algorithm to use. Accepted values are: “consistent-hashing”, “least-connections”, “round-robin”. Default: “round-robin”.
hash_on
optional
What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”. Default: “none”.
hash_fallback
optional
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. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”. Default: “none”.
hash_on_header
semi-optional
The header name to take the value from as hash input. Only required when hash_on is set to header.
hash_fallback_header
semi-optional
The header name to take the value from as hash input. Only required when hash_fallback is set to header.
hash_on_cookie
semi-optional
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.
hash_on_cookie_path
semi-optional
The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie. Default: “/“.
hash_on_query_arg
semi-optional
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.
hash_fallback_query_arg
semi-optional
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.
hash_on_uri_capture
semi-optional
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.
hash_fallback_uri_capture
semi-optional
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.
slots
optional
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. Default: 10000.
healthchecks.active.headers
optional
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.
healthchecks.active.https_sni
optional
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.
healthchecks.active.https_verify_certificateWhether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Default: true.
healthchecks.active.healthy.interval
optional
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.
healthchecks.active.healthy.http_statuses
optional
An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: [200, 302]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=302. With JSON, use an Array.
healthchecks.active.healthy.successes
optional
Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy. Default: 0.
healthchecks.active.unhealthy.tcp_failures
optional
Number of TCP failures in active probes to consider a target unhealthy. Default: 0.
healthchecks.active.unhealthy.http_statuses
optional
An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: [429, 404, 500, 501, 502, 503, 504, 505]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=404. With JSON, use an Array.
healthchecks.active.unhealthy.http_failures
optional
Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy. Default: 0.
healthchecks.active.unhealthy.interval
optional
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.
healthchecks.active.unhealthy.timeouts
optional
Number of timeouts in active probes to consider a target unhealthy. Default: 0.
healthchecks.active.http_path
optional
Path to use in GET HTTP request to run as a probe on active health checks. Default: “/“.
healthchecks.active.concurrency
optional
Number of targets to check concurrently in active health checks. Default: 10.
healthchecks.active.timeout
optional
Socket timeout for active health checks (in seconds). Default: 1.
healthchecks.active.type
optional
Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: “tcp”, “http”, “https”, “grpc”, “grpcs”. Default: “http”.
healthchecks.passive.healthy.successes
optional
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.
healthchecks.passive.healthy.http_statuses
optional
An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=201. With JSON, use an Array.
healthchecks.passive.unhealthy.tcp_failures
optional
Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: 0.
healthchecks.passive.unhealthy.http_statuses
optional
An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: [429, 500, 503]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=500. With JSON, use an Array.
healthchecks.passive.unhealthy.http_failures
optional
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.
healthchecks.passive.unhealthy.timeouts
optional
Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: 0.
healthchecks.passive.type
optional
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”.
healthchecks.threshold
optional
The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Default: 0.
tags
optional
An optional set of strings associated with the Upstream for grouping and filtering.
host_header
optional
The hostname to be used as Host header when proxying requests through Kong.
client_certificate
optional
If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is client_certificate.id=<client_certificate id>. With JSON, use ““client_certificate”:{“id”:”<client_certificate id>”}.

Inserts (or replaces) the Upstream under the requested resource with the definition specified in the body. The Upstream will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the Upstream being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new Upstream 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.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Upstream

Note: This API is not available in DB-less mode.

Delete Upstream

/upstreams/{upstream name or id}

AttributesDescription
upstream name or id
required
The unique identifier or the name of the Upstream to delete.
Delete Upstream Associated to a Specific Certificate

/certificates/{certificate id}/upstreams/{upstream name or id}

AttributesDescription
certificate id
required
The unique identifier of the Certificate to delete.
upstream name or id
required
The unique identifier or the name of the Upstream to delete.

Response

  1. HTTP 204 No Content

Show Upstream Health for Node

Displays the health status for all Targets of a given Upstream, or for the whole Upstream, according to the perspective of a specific Kong node. Note that, being node-specific information, making this same request to different nodes of the Kong cluster may produce different results. For example, one specific node of the Kong cluster may be experiencing network issues, causing it to fail to connect to some Targets: these Targets will be marked as unhealthy by that node (directing traffic from this node to other Targets that it can successfully reach), but healthy to all others Kong nodes (which have no problems using that Target).

The data field of the response contains an array of Target objects. The health for each Target is returned in its health field:

  • If a Target fails to be activated in the balancer due to DNS issues, its status displays as DNS_ERROR.
  • When health checks are not enabled in the Upstream configuration, the health status for active Targets is displayed as HEALTHCHECKS_OFF.
  • When health checks are enabled and the Target is determined to be healthy, either automatically or manually, its status is displayed as HEALTHY. This means that this Target is currently included in this Upstream’s load balancer execution.
  • When a Target has been disabled by either active or passive health checks (circuit breakers) or manually, its status is displayed as UNHEALTHY. The load balancer is not directing any traffic to this Target via this Upstream.

When the request query parameter balancer_health is set to 1, the data field of the response refers to the Upstream itself, and its health attribute is defined by the state of all of Upstream’s Targets, according to the field healthchecks.threshold.

/upstreams/{name or id}/health/

AttributesDescription
name or id
required
The unique identifier or the name of the Upstream for which to display Target health.

Request Querystring Parameters

AttributesDescription
balancer_health
optional
If set to 1, Kong will return the health status of the Upstream itself. See the healthchecks.threshold property.

Response

  1. HTTP 200 OK
  1. {
  2. "total": 2,
  3. "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9",
  4. "data": [
  5. {
  6. "created_at": 1485524883980,
  7. "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
  8. "health": "HEALTHY",
  9. "target": "127.0.0.1:20000",
  10. "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
  11. "weight": 100
  12. },
  13. {
  14. "created_at": 1485524914883,
  15. "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
  16. "health": "UNHEALTHY",
  17. "target": "127.0.0.1:20002",
  18. "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
  19. "weight": 200
  20. }
  21. ]
  22. }

If balancer_health=1:

  1. HTTP 200 OK
  1. {
  2. "data": {
  3. "health": "HEALTHY",
  4. "id": "07131005-ba30-4204-a29f-0927d53257b4"
  5. },
  6. "next": null,
  7. "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9"
  8. }

Target Object

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.

Targets can be both tagged and filtered by tags.

  1. {
  2. "id": "173a6cee-90d1-40a7-89cf-0329eca780a6",
  3. "created_at": 1422386534,
  4. "upstream": {"id":"bdab0e47-4e37-4f0b-8fd0-87d95cc4addc"},
  5. "target": "example.com:8000",
  6. "weight": 100,
  7. "tags": ["user-level", "low-priority"]
  8. }

Update Target

Note: This API is not available in DB-less mode.

Update a target.

/upstreams/{upstream name or id}/targets/{host:port or id}

AttributesDescription
upstream name or id
required
The unique identifier or the name of the upstream for which to update the target.
host:port or id
required
The host:port combination element of the target to update, or the id of an existing target entry.

Response

  1. HTTP 201 Created

Delete Target

Note: This API is not available in DB-less mode.

Remove a target from the load balancer.

/upstreams/{upstream name or id}/targets/{host:port or id}

AttributesDescription
upstream name or id
required
The unique identifier or the name of the upstream for which to delete the target.
host:port or id
required
The host:port combination element of the target to remove, or the id of an existing target entry.

Response

  1. HTTP 204 No Content

Set Target Address As Healthy

Note: This API is not available in DB-less mode.

Set the current health status of an individual address resolved by a target in the load balancer to “healthy” in the entire Kong cluster.

This endpoint can be used to manually re-enable an address resolved by a target that was previously disabled by the upstream’s health checker. Upstreams only forward requests to healthy nodes, so this call tells Kong to start using this address again.

This resets the health counters of the health checkers running in all workers of the Kong node, and broadcasts a cluster-wide message so that the “healthy” status is propagated to the whole Kong cluster.

Note: This API is not available when Kong is running in hybrid mode.

/upstreams/{upstream name or id}/targets/{target or id}/{address}/healthy

AttributesDescription
upstream name or id
required
The unique identifier or the name of the upstream.
target or id
required
The host/port combination element of the target to set as healthy, or the id of an existing target entry.
address
required
The host/port combination element of the address to set as healthy.

Response

  1. HTTP 204 No Content

Set Target Address As Unhealthy

Note: This API is not available in DB-less mode.

Set the current health status of an individual address resolved by a target in the load balancer to “unhealthy” in the entire Kong cluster.

This endpoint can be used to manually disable an address and have it stop responding to requests. Upstreams only forward requests to healthy nodes, so this call tells Kong to start skipping this address.

This call resets the health counters of the health checkers running in all workers of the Kong node, and broadcasts a cluster-wide message so that the “unhealthy” status is propagated to the whole Kong cluster.

Active health checks continue to execute for unhealthy addresses. Note that if active health checks are enabled and the probe detects that the address is actually healthy, it will automatically re-enable it again. To permanently remove a target from the balancer, you should delete a target instead.

Note: This API is not available when Kong is running in hybrid mode.

/upstreams/{upstream name or id}/targets/{target or id}/{address}/unhealthy

AttributesDescription
upstream name or id
required
The unique identifier or the name of the upstream.
target or id
required
The host/port combination element of the target to set as unhealthy, or the id of an existing target entry.

Response

  1. HTTP 204 No Content

Set Target As Healthy

Set the current health status of a target in the load balancer to “healthy” in the entire Kong cluster. This sets the “healthy” status to all addresses resolved by this target.

This endpoint can be used to manually re-enable a target that was previously disabled by the upstream’s health checker. Upstreams only forward requests to healthy nodes, so this call tells Kong to start using this target again.

This resets the health counters of the health checkers running in all workers of the Kong node, and broadcasts a cluster-wide message so that the “healthy” status is propagated to the whole Kong cluster.

Note: This API is not available when Kong is running in hybrid mode.

/upstreams/{upstream name or id}/targets/{target or id}/healthy

AttributesDescription
upstream name or id
required
The unique identifier or the name of the upstream.
target or id
required
The host/port combination element of the target to set as healthy, or the id of an existing target entry.

Response

  1. HTTP 204 No Content

Set Target As Unhealthy

Set the current health status of a target in the load balancer to “unhealthy” in the entire Kong cluster. This sets the “unhealthy” status to all addresses resolved by this target.

This endpoint can be used to manually disable a target and have it stop responding to requests. Upstreams only forward requests to healthy nodes, so this call tells Kong to start skipping this target.

This call resets the health counters of the health checkers running in all workers of the Kong node, and broadcasts a cluster-wide message so that the “unhealthy” status is propagated to the whole Kong cluster.

Active health checks continue to execute for unhealthy targets. Note that if active health checks are enabled and the probe detects that the target is actually healthy, it will automatically re-enable it again. To permanently remove a target from the balancer, you should delete a target instead.

Note: This API is not available when Kong is running in hybrid mode.

/upstreams/{upstream name or id}/targets/{target or id}/unhealthy

AttributesDescription
upstream name or id
required
The unique identifier or the name of the upstream.
target or id
required
The host/port combination element of the target to set as unhealthy, or the id of an existing target entry.

Response

  1. HTTP 204 No Content

List All Targets

Lists all targets of the upstream. Multiple target objects for the same target may be returned, showing the history of changes for a specific target. The target object with the latest created_at is the current definition.

/upstreams/{name or id}/targets/all/

AttributesDescription
name or id
required
The unique identifier or the name of the upstream for which to list the targets.

Response

  1. HTTP 200 OK
  1. {
  2. "total": 2,
  3. "data": [
  4. {
  5. "created_at": 1485524883980,
  6. "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
  7. "target": "127.0.0.1:20000",
  8. "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
  9. "weight": 100
  10. },
  11. {
  12. "created_at": 1485524914883,
  13. "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
  14. "target": "127.0.0.1:20002",
  15. "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
  16. "weight": 200
  17. }
  18. ]
  19. }

Vaults Entity

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.

Vaults can be both tagged and filtered by tags.

  1. {
  2. "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5",
  3. "prefix": "env",
  4. "name": "env",
  5. "description": "This vault is used to retrieve redis database access credentials",
  6. "config": {"prefix":"SSL_"},
  7. "created_at": 1422386534,
  8. "updated_at": 1422386534,
  9. "tags": ["database-credentials", "data-plane"]
  10. }

Add Vault

Note: This API is not available in DB-less mode.

Create Vault

/vaults

Request Body

AttributesDescription
prefixThe 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.
nameThe name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance.
description
optional
The description of the Vault entity.
config
optional
The configuration properties for the Vault which can be found on the vaults’ documentation page.
tags
optional
An optional set of strings associated with the Vault for grouping and filtering.

Response

  1. HTTP 201 Created
  1. {
  2. "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5",
  3. "prefix": "env",
  4. "name": "env",
  5. "description": "This vault is used to retrieve redis database access credentials",
  6. "config": {"prefix":"SSL_"},
  7. "created_at": 1422386534,
  8. "updated_at": 1422386534,
  9. "tags": ["database-credentials", "data-plane"]
  10. }

List Vaults

List All Vaults

/vaults

Response

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3. "id": "518BBE43-2454-4559-99B0-8E7D1CD3E8C8",
  4. "prefix": "env",
  5. "name": "env",
  6. "description": "This vault is used to retrieve redis database access credentials",
  7. "config": {"prefix":"SSL_"},
  8. "created_at": 1422386534,
  9. "updated_at": 1422386534,
  10. "tags": ["database-credentials", "data-plane"]
  11. }, {
  12. "id": "7C4747E9-E831-4ED8-9377-83A6F8A37603",
  13. "prefix": "env",
  14. "name": "env",
  15. "description": "This vault is used to retrieve redis database access credentials",
  16. "config": {"prefix":"SSL_"},
  17. "created_at": 1422386534,
  18. "updated_at": 1422386534,
  19. "tags": ["certificates", "critical"]
  20. }],
  21. "next": "http://localhost:8001/vaults?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  22. }

Retrieve Vault

Retrieve Vault

/vaults/{vault prefix or id}

AttributesDescription
vault prefix or id
required
The unique identifier or the prefix of the Vault to retrieve.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5",
  3. "prefix": "env",
  4. "name": "env",
  5. "description": "This vault is used to retrieve redis database access credentials",
  6. "config": {"prefix":"SSL_"},
  7. "created_at": 1422386534,
  8. "updated_at": 1422386534,
  9. "tags": ["database-credentials", "data-plane"]
  10. }

Update Vault

Note: This API is not available in DB-less mode.

Update Vault

/vaults/{vault prefix or id}

AttributesDescription
vault prefix or id
required
The unique identifier or the prefix of the Vault to update.

Request Body

AttributesDescription
prefixThe 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.
nameThe name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance.
description
optional
The description of the Vault entity.
config
optional
The configuration properties for the Vault which can be found on the vaults’ documentation page.
tags
optional
An optional set of strings associated with the Vault for grouping and filtering.

Response

  1. HTTP 200 OK
  1. {
  2. "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5",
  3. "prefix": "env",
  4. "name": "env",
  5. "description": "This vault is used to retrieve redis database access credentials",
  6. "config": {"prefix":"SSL_"},
  7. "created_at": 1422386534,
  8. "updated_at": 1422386534,
  9. "tags": ["database-credentials", "data-plane"]
  10. }

Update Or Create Vault

Note: This API is not available in DB-less mode.

Create Or Update Vault

/vaults/{vault prefix or id}

AttributesDescription
vault prefix or id
required
The unique identifier or the prefix of the Vault to create or update.

Request Body

AttributesDescription
prefixThe 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.
nameThe name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance.
description
optional
The description of the Vault entity.
config
optional
The configuration properties for the Vault which can be found on the vaults’ documentation page.
tags
optional
An optional set of strings associated with the Vault for grouping and filtering.

Inserts (or replaces) the Vault under the requested resource with the definition specified in the body. The Vault will be identified via the prefix or id attribute.

When the prefix or id attribute has the structure of a UUID, the Vault being inserted/replaced will be identified by its id. Otherwise it will be identified by its prefix.

When creating a new Vault without specifying id (neither in the URL nor in the body), then it will be auto-generated.

Notice that specifying a prefix in the URL and a different one in the request body is not allowed.

Response

  1. HTTP 200 OK

See POST and PATCH responses.


Delete Vault

Note: This API is not available in DB-less mode.

Delete Vault

/vaults/{vault prefix or id}

AttributesDescription
vault prefix or id
required
The unique identifier or the prefix of the Vault to delete.

Response

  1. HTTP 204 No Content