CINXE.COM

<!DOCTYPE html> <html lang="en-US" itemscope itemtype="http://schema.org/Article"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">  <script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" type="text/javascript" charset="UTF-8" data-domain-script="2c4de954-6bec-4e93-8086-64cb113f151a"> </script> <script type="text/javascript"> function OptanonWrapper() { } </script>   <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer', 'GTM-NL48VKT');</script>  <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Admin API - Kong Gateway - v2.8.x | Kong Docs</title> <meta name="description" content="Documentation for Kong, the Cloud Connectivity Company for APIs and Microservices."> <meta name="author" content="KongHQ"> <meta property="og:title" content="Admin API - Kong Gateway - v2.8.x | Kong Docs"> <meta property="og:site_name" content="Kong Docs">  <meta property="og:url" content="https://docs.konghq.com"> <meta property="og:description" content="Documentation for Kong, the Cloud Connectivity Company for APIs and Microservices."> <meta property="og:type" content="website"> <meta property="og:locale" content="en_US"> <meta property="og:image" content="https://docs.konghq.com/assets/images/share.png"> <meta name="twitter:card" content="summary_large_image"> <meta name="twitter:site" content="@thekonginc"> <meta name="twitter:creator" content="@thekonginc"> <meta name="twitter:url" content="https://docs.konghq.com"> <meta name="twitter:description" content="Documentation for Kong, the Cloud Connectivity Company for APIs and Microservices."> <meta name="twitter:image" content="https://docs.konghq.com/assets/images/share.png"> <meta property="fb:admins" content="227304446"> <meta property="fb:admins" content="576641408"> <meta name="google-site-verification" content="CrU3zp02dNKTe8NSAipL4NCPkrIjDXG8fViTZ-MIzP4"> <script type="application/ld+json"> { "@context": "http://schema.org", "@type": "Organization", "name": "KongHQ", "url": "https://docs.konghq.com", "logo": "https://docs.konghq.com/assets/images/logo.png", "sameAs": [ "https://www.facebook.com/konginc", "https://twitter.com/thekonginc", "https://plus.google.com/+mashape" ] } </script>  <link rel="dns-prefetch" href="https://cloud.typography.com"> <link rel="dns-prefetch" href="https://dev.visualwebsiteoptimizer.com"> <link rel="dns-prefetch" href="https://cdn.segment.com"> <link rel="icon" type="image/x-icon" href="/assets/images/favicon.ico"> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3"> <link rel="canonical" href="https://docs.konghq.com/gateway/latest/admin-api/"> <link rel="alternate" hreflang="x-default" href="https://docs.konghq.com/gateway/2.8.x/admin-api/"> <link rel="alternate" hreflang="ja" href="https://docs.jp.konghq.com/gateway/2.8.x/admin-api/"> <meta name="robots" content="follow,noindex">  <script src="https://kit.fontawesome.com/1332a92967.js" crossorigin="anonymous"> </script> <script src="/vite/assets/application-D8sXFsvE.js" crossorigin="anonymous" type="module"></script> <link href="/vite/assets/_commonjsHelpers-Cpj98o6Y.js" rel="modulepreload" as="script" crossorigin="anonymous"> <link rel="stylesheet" href="/vite/assets/application-C5Quk452.css" media="screen"> </head> <body id="" data-spy="scroll" data-target="#scroll-sidebar" data-offset="350">  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NL48VKT" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>  <header class="navbar-v2 closed"> <a class="skip-main" href="#main">Skip to content</a>    <div class="navbar-content"> <a href="https://konghq.com" class="navbar-brand col col-xl-auto" target="_blank" rel="noopener noreferrer"> <img src="/assets/images/logos/konglogo-dark-theme.svg" alt="Kong Logo" id="kong-logo"> </a> | <a href="/" class="navbar-brand col col-xl-auto"> <img src="/assets/images/logos/docslogo-dark-theme.svg" alt="Kong Docs Logo" id="kong-docs-logo"> </a> <div class="separator mobile"></div> <div class="search-input-wrapper" id="getkong-algolia-search-input"> </div> <div class="search-results-wrapper"></div> <div class="navbar-items" role="navigation" aria-label="Main menu"> <ul class="navbar-items" role="menubar"> <li id="top-module-list" aria-haspopup="true" role="menuitem" aria-expanded="false" class="navbar-item main-menu-item with-submenu active"> Docs <ul class="navbar-item-submenu" role="menu"> <div class="submenu-section"> <li role="menuitem" class="docs-dropdown-li"> <a href="/api/" class="docs-dropdown-li__link" tabindex="-1"> <div class="docs-dropdown-li__card"> Explore the API Specs <div class="docs-dropdown-li__card-link"> <img src="/assets/images/landing-page/view-all-api-specs.png" alt="View all API Specs"> View all API Specs <img src="/assets/images/landing-page/arrow-right.svg" alt="View all API Specs arrow image"> </div> </div> </a> </li> <li role="menuitem" class="docs-dropdown-li" tabindex="-1"> <div class="docs-dropdown-li__section"> <div class="docs-dropdown-li__section-title"> Documentation </div> <div class="docs-dropdown-li__section-items"> <a class="item item-all" href="/api/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">API Specs</div> </div> </a> <a class="item" href="/gateway/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Gateway</div> <div class="item__description-desc">Lightweight, fast, and flexible cloud-native API gateway</div> </div> </a> <a class="item" href="/konnect/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Konnect</div> <div class="item__description-desc">Single platform for SaaS end-to-end connectivity</div> </div> </a> <a class="item" href="/gateway/latest/ai-gateway/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong AI Gateway</div> <div class="item__description-desc">Multi-LLM AI Gateway for GenAI infrastructure</div> </div> </a> <a class="item" href="/mesh/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Mesh</div> <div class="item__description-desc">Enterprise service mesh based on Kuma and Envoy</div> </div> </a> <a class="item" href="/deck/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">decK</div> <div class="item__description-desc">Helps manage Kong’s configuration in a declarative fashion</div> </div> </a> <a class="item" href="/kubernetes-ingress-controller/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Ingress Controller</div> <div class="item__description-desc">Works inside a Kubernetes cluster and configures Kong to proxy traffic</div> </div> </a> <a class="item" href="/gateway-operator/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Gateway Operator</div> <div class="item__description-desc">Manage your Kong deployments on Kubernetes using YAML Manifests</div> </div> </a> <a class="item" href="https://docs.insomnia.rest/" tabindex="-1" target="_blank" rel="noopener nofollow noreferrer "> <div class="item__description"> <div class="item__description-title">Insomnia</div> <div class="item__description-desc">Collaborative API development platform</div> </div> </a> </div> </div> </li> </div> </ul> </li> <li role="menuitem" aria-haspopup="true" aria-expanded="false" class="navbar-item main-menu-item with-submenu navbar-item-hub"> Plugin Hub <ul class="navbar-item-submenu" role="menu"> <div class="submenu-section"> <li role="menuitem" class="docs-dropdown-li"> <a href="/hub/" class="docs-dropdown-li__link" tabindex="-1"> <div class="docs-dropdown-li__card"> Explore the Plugin Hub <div class="docs-dropdown-li__card-link"> <img src="/assets/images/landing-page/view-all-plugins.svg" alt="View all plugins"> View all plugins <img src="/assets/images/landing-page/arrow-right.svg" alt="View all plugins arrow image"> </div> </div> </a> </li> <li role="menuitem" class="docs-dropdown-li"> <div class="docs-dropdown-li__section"> <div class="docs-dropdown-li__section-title"> Functionality <a href="/hub/" class="view-all" tabindex="-1"> View all <img src="/assets/images/landing-page/arrow-right.svg" alt="View all arrow image"> </a> </div> <div class="docs-dropdown-li__section-items"> <a class="item item-all" href="/hub/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">View all plugins</div> </div> </a> <a class="item" href="/hub/?category=ai" tabindex="-1"> <div> <img src="/assets/images/nav/hub/ai.svg" alt="AI's icon"> </div> <div class="item__description"> <div class="item__description-title">AI</div> <div class="item__description-desc">Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins</div> </div> </a> <a class="item" href="/hub/?category=authentication" tabindex="-1"> <div> <img src="/assets/images/nav/hub/lock_person.svg" alt="Authentication's icon"> </div> <div class="item__description"> <div class="item__description-title">Authentication</div> <div class="item__description-desc">Protect your services with an authentication layer</div> </div> </a> <a class="item" href="/hub/?category=security" tabindex="-1"> <div> <img src="/assets/images/nav/hub/shield.svg" alt="Security's icon"> </div> <div class="item__description"> <div class="item__description-title">Security</div> <div class="item__description-desc">Protect your services with additional security layer</div> </div> </a> <a class="item" href="/hub/?category=traffic-control" tabindex="-1"> <div> <img src="/assets/images/nav/hub/route.svg" alt="Traffic Control's icon"> </div> <div class="item__description"> <div class="item__description-title">Traffic Control</div> <div class="item__description-desc">Manage, throttle and restrict inbound and outbound API traffic</div> </div> </a> <a class="item" href="/hub/?category=serverless" tabindex="-1"> <div> <img src="/assets/images/nav/hub/serverless.svg" alt="Serverless's icon"> </div> <div class="item__description"> <div class="item__description-title">Serverless</div> <div class="item__description-desc">Invoke serverless functions in combination with other plugins</div> </div> </a> <a class="item" href="/hub/?category=analytics-monitoring" tabindex="-1"> <div> <img src="/assets/images/nav/hub/bar_chart.svg" alt="Analytics & Monitoring's icon"> </div> <div class="item__description"> <div class="item__description-title">Analytics & Monitoring</div> <div class="item__description-desc">Visualize, inspect and monitor APIs and microservices traffic</div> </div> </a> <a class="item" href="/hub/?category=transformations" tabindex="-1"> <div> <img src="/assets/images/nav/hub/swap_horiz.svg" alt="Transformations's icon"> </div> <div class="item__description"> <div class="item__description-title">Transformations</div> <div class="item__description-desc">Transform request and responses on the fly on Kong</div> </div> </a> <a class="item" href="/hub/?category=logging" tabindex="-1"> <div> <img src="/assets/images/nav/hub/list_alt.svg" alt="Logging's icon"> </div> <div class="item__description"> <div class="item__description-title">Logging</div> <div class="item__description-desc">Log request and response data using the best transport for your infrastructure</div> </div> </a> </div> </div> </li> </div> </ul> </li> <li role="menuitem" class="main-menu-item"> <a href="https://support.konghq.com/" class="navbar-item" target="_blank" rel="noopener nofollow noreferrer ">Support</a> </li> <li role="menuitem" class="main-menu-item"> <a href="https://konghq.com/community/" class="navbar-item" target="_blank" rel="noopener noreferrer">Community</a> </li> <li role="menuitem" class="main-menu-item"> <a href="https://education.konghq.com" class="navbar-item" target="_blank" rel="noopener nofollow noreferrer ">Kong Academy</a> </li> </ul> <a id="top-cta" href="https://konghq.com/contact-sales?utm_source=docs.konghq.com" class="navbar-button" target="_blank" rel="noopener nofollow noreferrer "> Get a Demo </a> <a id="konnect-cta" href="https://konghq.com/products/kong-konnect/register?utm_medium=referral&utm_source=docs&utm_campaign=gateway-konnect&utm_content=top-nav" class="navbar-button" target="_blank" rel="noopener nofollow noreferrer "> Start Free Trial </a> </div> <div id="navbar-menu-toggle-button" class="small-screen-button" aria-label="Toggle navigation"> <div></div> <div></div> <div></div> </div> </div> </header> <div class="page v2 " data-url="/gateway/2.8.x/admin-api/"> <div class="page--header-background page--header-background-doc"></div> <div class="container"> <header class="page-header page-header-doc"> <div class="page-header-product-version"> <div class="edition"> Kong Gateway </div> <div class="version"> 2.8.x LTS </div> </div> <div class="page-header--nav"> <ul class="breadcrumbs"> <li class="breadcrumb-item"> <a href="/"> <img src="/assets/images/icons/hub-layout/icn-breadcrumbs.svg" alt="Home icon"> </a> </li> <li class="breadcrumb-item"> <a href="/gateway/2.8.x/">Kong Gateway</a> </li> <li class="breadcrumb-item"> <a href="/gateway/2.8.x/admin-api/">Admin API</a> </li> </ul> <div class="github-links"> <div class="github-links--edit"> <a href="https://github.com/Kong/docs.konghq.com/edit/main/app/gateway/2.8.x/admin-api/index.md" target="_blank" rel="noopener nofollow noreferrer "> <img src="/assets/images/icons/third-party/logo-github-white.svg" alt="github-edit-page">Edit this page </a> </div> <div class="github-links--issues"> <a href="https://github.com/Kong/docs.konghq.com/issues/" target="_blank" rel="noopener nofollow noreferrer "> <img src="/assets/images/icons/documentation/icn-monitoring-white.svg" alt="report-issue">Report an issue</a> </div> </div> </div> </header> <aside class="docs-sidebar"> <div class="sidebar-title-container"> <div class="docsets-dropdown dropdown"> <button class="dropdown-button" id="module-dropdown" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" tabindex="0"> Kong Gateway </button> <ul class="dropdown-menu dropdown-menu-right with-submenu" id="module-list" role="menu" aria-labelledby="module-dropdown" aria-hidden="true"> <li role="menuitem" tabindex="-1" class="active"> <a href="/gateway/latest/" class="active">Kong Gateway</a> </li> <li role="menuitem" tabindex="-1"> <a href="/konnect/">Kong Konnect</a> </li> <li role="menuitem" tabindex="-1"> <a href="/mesh/latest/">Kong Mesh</a> </li> <li role="menuitem" tabindex="-1"> <a href="/hub/?category=ai">Kong AI Gateway</a> </li> <li role="menuitem" tabindex="-1"> <a href="/hub/">Plugin Hub</a> </li> <li role="menuitem" tabindex="-1"> <a href="/deck/">decK</a> </li> <li role="menuitem" tabindex="-1"> <a href="/kubernetes-ingress-controller/latest/">Kong Ingress Controller</a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway-operator/latest/">Kong Gateway Operator</a> </li> <li> <a href="https://docs.insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer ">Insomnia</a> </li> <li role="menuitem" tabindex="-1"> <a href="https://kuma.io/docs/" target="_blank" rel="noopener nofollow noreferrer ">Kuma</a> </li> <hr> <li role="menuitem" tabindex="-1"> <a href="/contributing/">Docs contribution guidelines</a> </li> </ul> </div> <div class="versions-dropdown dropdown"> <button class="dropdown-button" id="version-dropdown" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" tabindex="0"> Version 2.8.x (LTS) </button> <ul class="dropdown-menu dropdown-menu-right" id="version-list" role="menu" aria-labelledby="version-dropdown" aria-hidden="true"> <li role="menuitem" tabindex="-1"> <a href="/gateway/unreleased/admin-api/" data-version-id="3.10.x"> unreleased </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.9.x/admin-api/" data-version-id="3.9.x"> 3.9.x (latest) </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.8.x/admin-api/" data-version-id="3.8.x"> 3.8.x </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.7.x/admin-api/" data-version-id="3.7.x"> 3.7.x </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.6.x/admin-api/" data-version-id="3.6.x"> 3.6.x </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.5.x/admin-api/" data-version-id="3.5.x"> 3.5.x </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.4.x/admin-api/" data-version-id="3.4.x"> 3.4.x (LTS) </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.3.x/admin-api/" data-version-id="3.3.x"> 3.3.x </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.2.x/admin-api/" data-version-id="3.2.x"> 3.2.x </a> </li> <li role="menuitem" tabindex="-1"> <a href="/gateway/3.1.x/admin-api/" data-version-id="3.1.x"> 3.1.x </a> </li> <li class="active" role="menuitem" tabindex="-1"> <a href="/gateway/2.8.x/admin-api/" class="active" data-version-id="2.8.x"> 2.8.x (LTS) </a> </li> <li role="menuitem" tabindex="-1"> <a href="https://legacy-gateway--kongdocs.netlify.app/" target="_blank" rel="noopener nofollow noreferrer "> Archive (3.0.x and pre-2.8.x) </a> </li> </ul> </div> </div> <ul class="sidebar-container" role="tree" aria-label="Documentation"> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-flag.svg" alt=""> Introduction <button class="sidebar-tree-toggle" aria-label="toggle Introduction subtree" tabindex="-1"> </button> <ul class="items" id="id-1-introduction-subtree" role="group" aria-label="Introduction"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/"> Overview of Kong Gateway </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/support-policy/"> Version Support Policy </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/availability-stages/"> Stages of Software Availability </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/changelog/"> Changelog </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-deployment-color.svg" alt=""> Install and Run <button class="sidebar-tree-toggle" aria-label="toggle Install and Run subtree" tabindex="-1"> </button> <ul class="items" id="id-2-install-and-run-subtree" role="group" aria-label="Install and Run"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/"> Overview </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/kubernetes/"> Kubernetes </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/helm/"> Helm </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/openshift/"> OpenShift with Helm </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/docker/"> Docker </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/amazon-linux/"> Amazon Linux </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/centos/"> CentOS </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/debian/"> Debian </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/rhel/"> RHEL </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/ubuntu/"> Ubuntu </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/migrate-ce-to-ke/"> Migrating from OSS to EE </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/upgrade-enterprise/"> Upgrade Kong Gateway </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/install-and-run/upgrade-oss/"> Upgrade Kong Gateway OSS </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/3.4.x/upgrade/lts-upgrade/"> Upgrade from 2.8 LTS to 3.4 LTS </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-quickstart-color.svg" alt=""> Get Started <button class="sidebar-tree-toggle" aria-label="toggle Get Started subtree" tabindex="-1"> </button> <ul class="items" id="id-3-get-started-subtree" role="group" aria-label="Get Started"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/quickstart/"> Quickstart Guide </a> <button class="sidebar-tree-toggle" aria-label="toggle Quickstart Guide subtree" tabindex="-1"> </button> <ul class="items" id="id-3-1-quickstart-guide-subtree" role="group" aria-label="Quickstart Guide"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/quickstart/configuring-a-service/"> Configuring a Service </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/quickstart/configuring-a-grpc-service/"> Configuring a gRPC Service </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/quickstart/enabling-plugins/"> Enabling Plugins </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/quickstart/adding-consumers/"> Adding Consumers </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/"> Comprehensive Guide </a> <button class="sidebar-tree-toggle" aria-label="toggle Comprehensive Guide subtree" tabindex="-1"> </button> <ul class="items" id="id-3-2-comprehensive-guide-subtree" role="group" aria-label="Comprehensive Guide"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/prepare/"> Prepare to Administer </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/expose-services/"> Expose your Services </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/protect-services/"> Protect your Services </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/improve-performance/"> Improve Performance </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/secure-services/"> Secure Services </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/load-balancing/"> Set Up Intelligent Load Balancing </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/manage-teams/"> Manage Administrative Teams </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/get-started/comprehensive/dev-portal/"> Publish, Locate, and Consume Services </a> </li> </ul> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-deployment-color.svg" alt=""> Plan and Deploy <button class="sidebar-tree-toggle" aria-label="toggle Plan and Deploy subtree" tabindex="-1"> </button> <ul class="items" id="id-4-plan-and-deploy-subtree" role="group" aria-label="Plan and Deploy"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/kong-user/"> Running Kong as a Non-Root User </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/sizing-guidelines/"> Resource Sizing Guidelines </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/hybrid-mode/"> Hybrid Mode </a> <button class="sidebar-tree-toggle" aria-label="toggle Hybrid Mode subtree" tabindex="-1"> </button> <ul class="items" id="id-4-3-hybrid-mode-subtree" role="group" aria-label="Hybrid Mode"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/hybrid-mode/hybrid-mode-setup/"> Deploy Kong Gateway in Hybrid Mode </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/kubernetes-deployment-options/"> Kubernetes Deployment Options </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/systemd/"> Control Kong Gateway through systemd </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/performance-testing-framework/"> Performance Testing Framework </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/dns-considerations/"> DNS Considerations </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/default-ports/"> Default Ports </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/licenses/"> Licenses </a> <button class="sidebar-tree-toggle" aria-label="toggle Licenses subtree" tabindex="-1"> </button> <ul class="items" id="id-4-9-licenses-subtree" role="group" aria-label="Licenses"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/licenses/access-license/"> Access Your License </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/licenses/deploy-license/"> Deploy Your License </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/licenses/report/"> Monitor License Usage </a> </li> </ul> </li> <li class="sidebar-item" role="none"> Security <button class="sidebar-tree-toggle" aria-label="toggle Security subtree" tabindex="-1"> </button> <ul class="items" id="id-4-10-security-subtree" role="group" aria-label="Security"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/start-kong-securely/"> Start Kong Gateway Securely </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/db-encryption/"> Keyring and Data Encryption </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/kong-security-update-process/"> Kong Security Update Process </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/"> Secrets Management </a> <button class="sidebar-tree-toggle" aria-label="toggle Secrets Management subtree" tabindex="-1"> </button> <ul class="items" id="id-4-10-4-secrets-management-subtree" role="group" aria-label="Secrets Management"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/getting-started/"> Getting Started </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/advanced-usage/"> Advanced Usage </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/backends/"> Backends </a> <button class="sidebar-tree-toggle" aria-label="toggle Backends subtree" tabindex="-1"> </button> <ul class="items" id="id-4-10-4-3-backends-subtree" role="group" aria-label="Backends"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/backends/env/"> Environment Variables </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/backends/aws-sm/"> AWS Secrets Manager </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/backends/gcp-sm/"> GCP Secret Manager </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/backends/hashicorp-vault/"> HashiCorp Vault </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plan-and-deploy/security/secrets-management/reference-format/"> Reference Format </a> </li> </ul> </li> </ul> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/konnect/konnect-settings.svg" alt=""> Configure <button class="sidebar-tree-toggle" aria-label="toggle Configure subtree" tabindex="-1"> </button> <ul class="items" id="id-5-configure-subtree" role="group" aria-label="Configure"> <li class="sidebar-item" role="none"> Authentication and Authorization <button class="sidebar-tree-toggle" aria-label="toggle Authentication and Authorization subtree" tabindex="-1"> </button> <ul class="items" id="id-5-1-authentication-and-authorization-subtree" role="group" aria-label="Authentication and Authorization"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/"> Authentication Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-use-case/"> OpenID Connect Plugin </a> <button class="sidebar-tree-toggle" aria-label="toggle OpenID Connect Plugin subtree" tabindex="-1"> </button> <ul class="items" id="id-5-1-2-openid-connect-plugin-subtree" role="group" aria-label="OpenID Connect Plugin"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-curity/"> OpenID Connect with Curity </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-azuread/"> OpenID Connect with Azure AD </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-google/"> OpenID Connect with Google </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-okta/"> OpenID Connect with Okta </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-auth0/"> OpenID Connect with Auth0 </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/oidc-cognito/"> OpenID Connect with Cognito </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/openid-connect/"> OpenID Connect Plugin Reference </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/allowing-multiple-authentication-methods/"> Allowing Multiple Authentication Methods </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/"> Auth for Kong Manager </a> <button class="sidebar-tree-toggle" aria-label="toggle Auth for Kong Manager subtree" tabindex="-1"> </button> <ul class="items" id="id-5-1-4-auth-for-kong-manager-subtree" role="group" aria-label="Auth for Kong Manager"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/super-admin/"> Create a Super Admin </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/networking/"> Configure Networking </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/email/"> Configure Kong Manager to Send Email </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/reset-password/"> Reset Passwords and RBAC Tokens </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/workspaces/"> Configure Workspaces </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/basic/"> Basic Auth </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/ldap/"> LDAP </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/oidc-mapping/"> OIDC </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/kong-manager/sessions/"> Sessions </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/rbac/"> Role-based Access Control (RBAC) </a> <button class="sidebar-tree-toggle" aria-label="toggle Role-based Access Control (RBAC) subtree" tabindex="-1"> </button> <ul class="items" id="id-5-1-5-role-based-access-control-rbac-subtree" role="group" aria-label="Role-based Access Control (RBAC)"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/rbac/add-role/"> Add a Role </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/rbac/add-user/"> Add a User </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/rbac/add-admin/"> Add an Admin </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/auth/service-directory-mapping/"> Mapping LDAP Service Directory Groups to Kong Roles </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/grpc/"> Configure gRPC Plugins </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/graphql-quickstart/"> GraphQL Quickstart </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/logging/"> Logging Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/configure/network/"> Network and Firewall </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-dev-portal-color.svg" alt=""> Dev Portal <button class="sidebar-tree-toggle" aria-label="toggle Dev Portal subtree" tabindex="-1"> </button> <ul class="items" id="id-6-dev-portal-subtree" role="group" aria-label="Dev Portal"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/"> Overview </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/enable-dev-portal/"> Enable the Dev Portal </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/structure-and-file-types/"> Structure and File Types </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/dev-portal/api/v1/"> Portal API Documentation </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/working-with-templates/"> Working with Templates </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/using-the-editor/"> Using the Editor </a> </li> <li class="sidebar-item" role="none"> Configuration <button class="sidebar-tree-toggle" aria-label="toggle Configuration subtree" tabindex="-1"> </button> <ul class="items" id="id-6-7-configuration-subtree" role="group" aria-label="Configuration"> <li class="sidebar-item" role="none"> Authentication <button class="sidebar-tree-toggle" aria-label="toggle Authentication subtree" tabindex="-1"> </button> <ul class="items" id="id-6-7-1-authentication-subtree" role="group" aria-label="Authentication"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/authentication/basic-auth/"> Basic Auth </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/authentication/key-auth/"> Key Auth </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/authentication/oidc/"> OIDC </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/authentication/sessions/"> Sessions </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/authentication/adding-registration-fields/"> Adding Custom Registration Fields </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/smtp/"> SMTP </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/configuration/workspaces/"> Workspaces </a> </li> </ul> </li> <li class="sidebar-item" role="none"> Administration <button class="sidebar-tree-toggle" aria-label="toggle Administration subtree" tabindex="-1"> </button> <ul class="items" id="id-6-8-administration-subtree" role="group" aria-label="Administration"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/managing-developers/"> Manage Developers </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/developer-permissions/"> Developer Roles and Content Permissions </a> </li> <li class="sidebar-item" role="none"> Application Registration <button class="sidebar-tree-toggle" aria-label="toggle Application Registration subtree" tabindex="-1"> </button> <ul class="items" id="id-6-8-3-application-registration-subtree" role="group" aria-label="Application Registration"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/auth-provider-strategy/"> Authorization Provider Strategy </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/enable-application-registration/"> Enable Application Registration </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/enable-key-auth-plugin/"> Enable Key Authentication for Application Registration </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/3rd-party-oauth/"> External OAuth2 Support </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/okta-config/"> Set up Okta and Kong for external OAuth </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/azure-oidc-config/"> Set Up Azure AD and Kong for External Authentication </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/administration/application-registration/managing-applications/"> Manage Applications </a> </li> </ul> </li> </ul> </li> <li class="sidebar-item" role="none"> Customization <button class="sidebar-tree-toggle" aria-label="toggle Customization subtree" tabindex="-1"> </button> <ul class="items" id="id-6-9-customization-subtree" role="group" aria-label="Customization"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/easy-theme-editing/"> Easy Theme Editing </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/migrating-templates/"> Migrating Templates Between Workspaces </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/markdown-extended/"> Markdown Rendering Module </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/emails/"> Customizing Portal Emails </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/adding-javascript-assets/"> Adding and Using JavaScript Assets </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/single-page-app/"> Single Page App in Dev Portal </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/theme-customization/alternate-openapi-renderer/"> Alternate OpenAPI Renderer </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/developer-portal/helpers/cli/"> Helpers CLI </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-vitals.svg" alt=""> Monitor <button class="sidebar-tree-toggle" aria-label="toggle Monitor subtree" tabindex="-1"> </button> <ul class="items" id="id-7-monitor-subtree" role="group" aria-label="Monitor"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/vitals/"> Kong Vitals </a> <button class="sidebar-tree-toggle" aria-label="toggle Kong Vitals subtree" tabindex="-1"> </button> <ul class="items" id="id-7-1-kong-vitals-subtree" role="group" aria-label="Kong Vitals"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/vitals/vitals-metrics/"> Metrics </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/vitals/vitals-reports/"> Reports </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/vitals/vitals-influx-strategy/"> Vitals with InfluxDB </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/vitals/vitals-prometheus-strategy/"> Vitals with Prometheus </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/vitals/vitals-estimates/"> Estimate Vitals Storage in PostgreSQL </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/prometheus/"> Prometheus plugin </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/zipkin/"> Zipkin plugin </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <img src="/assets/images/icons/documentation/icn-references-color.svg" alt=""> Reference <button class="sidebar-tree-toggle" aria-label="toggle Reference subtree" tabindex="-1"> </button> <ul class="items" id="id-8-reference-subtree" role="group" aria-label="Reference"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/"> Admin API </a> <button class="sidebar-tree-toggle" aria-label="toggle Admin API subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-admin-api-subtree" role="group" aria-label="Admin API"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#db-less-mode"> DB-less Mode </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#declarative-configuration"> Declarative Configuration </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#supported-content-types"> Supported Content Types </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#information-routes"> Information Routes </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#health-routes"> Health Routes </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#tags"> Tags </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#service-object"> Service Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#route-object"> Route Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#consumer-object"> Consumer Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#plugin-object"> Plugin Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#certificate-object"> Certificate Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#ca-certificate-object"> CA Certificate Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#sni-object"> SNI Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#upstream-object"> Upstream Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#target-object"> Target Object </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/#vaults-beta-entity"> Vaults Beta </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/licenses/reference/"> Licenses </a> <button class="sidebar-tree-toggle" aria-label="toggle Licenses subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-17-licenses-subtree" role="group" aria-label="Licenses"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/licenses/reference/"> Licenses Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/licenses/examples/"> Licenses Examples </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/workspaces/reference/"> Workspaces </a> <button class="sidebar-tree-toggle" aria-label="toggle Workspaces subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-18-workspaces-subtree" role="group" aria-label="Workspaces"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/workspaces/reference/"> Workspaces Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/workspaces/examples/"> Workspace Examples </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/rbac/reference/"> RBAC </a> <button class="sidebar-tree-toggle" aria-label="toggle RBAC subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-19-rbac-subtree" role="group" aria-label="RBAC"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/rbac/reference/"> RBAC Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/rbac/examples/"> RBAC Examples </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/admins/reference/"> Admins </a> <button class="sidebar-tree-toggle" aria-label="toggle Admins subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-20-admins-subtree" role="group" aria-label="Admins"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/admins/reference/"> API Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/admins/examples/"> Examples </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/developers/reference/"> Developers </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/consumer-groups/reference/"> Consumer Groups </a> <button class="sidebar-tree-toggle" aria-label="toggle Consumer Groups subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-22-consumer-groups-subtree" role="group" aria-label="Consumer Groups"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/consumer-groups/reference/"> API Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/consumer-groups/examples/"> Examples </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/event-hooks/reference/"> Event Hooks </a> <button class="sidebar-tree-toggle" aria-label="toggle Event Hooks subtree" tabindex="-1"> </button> <ul class="items" id="id-8-1-23-event-hooks-subtree" role="group" aria-label="Event Hooks"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/event-hooks/reference/"> Event Hooks Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/event-hooks/examples/"> Examples </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/audit-log/"> Audit Logging </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/db-encryption/"> Keyring and Data Encryption </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/admin-api/secure-admin-api/"> Securing the Admin API </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/db-less-and-declarative-config/"> DB-less and Declarative Configuration </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/configuration/"> Configuration Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/cli/"> CLI Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/loadbalancing/"> Load Balancing Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/proxy/"> Proxy Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/rate-limiting/"> Rate Limiting Library </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/health-checks-circuit-breakers/"> Health Checks and Circuit Breakers Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/clustering/"> Clustering Reference </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/"> Plugin Development Kit </a> <button class="sidebar-tree-toggle" aria-label="toggle Plugin Development Kit subtree" tabindex="-1"> </button> <ul class="items" id="id-8-10-plugin-development-kit-subtree" role="group" aria-label="Plugin Development Kit"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.client/"> kong.client </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.client.tls/"> kong.client.tls </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.cluster/"> kong.cluster </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.ctx/"> kong.ctx </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.ip/"> kong.ip </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.log/"> kong.log </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.nginx/"> kong.nginx </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.node/"> kong.node </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.request/"> kong.request </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.response/"> kong.response </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.router/"> kong.router </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.service/"> kong.service </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.service.request/"> kong.service.request </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.service.response/"> kong.service.response </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.table/"> kong.table </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/pdk/kong.vault/"> kong.vault </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/"> Plugin Development Guide </a> <button class="sidebar-tree-toggle" aria-label="toggle Plugin Development Guide subtree" tabindex="-1"> </button> <ul class="items" id="id-8-11-plugin-development-guide-subtree" role="group" aria-label="Plugin Development Guide"> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/"> Introduction </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/file-structure/"> File structure </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/custom-logic/"> Implementing custom logic </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/plugin-configuration/"> Plugin configuration </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/access-the-datastore/"> Accessing the datastore </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/custom-entities/"> Storing custom entities </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/entities-cache/"> Caching custom entities </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/admin-api/"> Extending the Admin API </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/tests/"> Writing tests </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/plugin-development/distribution/"> (un)Installing your plugin </a> </li> </ul> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/2.8.x/reference/external-plugins/"> Plugins in Other Languages </a> </li> <li class="sidebar-item" role="none"> <a class="sidebar-link" tabindex="-1" href="/gateway/3.0.x/reference/file-access-permissions/"> File Permissions Reference </a> </li> </ul> </li> </ul> </aside> <aside class="docs-toc"> <div id="oss-ee-toggle" data-current="Enterprise" style="display: none"> <img src="/assets/images/icons/icn-enterprise-black.svg" alt="enterprise-switcher-icon"> Switch to OSS </div> </aside> <div class="page-content-container page-content-container-doc v2 " id="documentation"> <div class="toggles "> </div> <div class="page-content"> <div class="content show-anchor-links"> <blockquote id="version-notice" class="important"> You are browsing documentation for an older version. See the <a href="/gateway/latest/admin-api/">latest documentation here</a>. </blockquote> <h1 tabindex="-1" id="main" class="page-content-title">Admin API </h1>  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. <ul> <li> <code class="language-plaintext highlighter-rouge">8001</code> is the default port on which the Admin API listens.</li> <li> <code class="language-plaintext highlighter-rouge">8444</code> is the default port for HTTPS traffic to the Admin API.</li> </ul> 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 <a href="/gateway/2.8.x/admin-api/secure-admin-api">this document</a> for a discussion of methods to secure the Admin API. <hr> <h2 id="db-less-mode">DB-less Mode</h2> In <a href="../reference/db-less-and-declarative-config">DB-less mode</a>, 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: <ul> <li><a href="#validate-a-configuration-against-a-schema">Validating configurations against schemas</a></li> <li><a href="#validate-a-plugin-configuration-against-the-schema">Validating plugin configurations against schemas</a></li> <li><a href="#reload-declarative-configuration">Reloading the declarative configuration</a></li> <li><a href="#set-target-as-healthy">Setting a target’s health status in the load balancer</a></li> </ul> <hr> <h2 id="declarative-configuration">Declarative Configuration</h2> Loading the declarative configuration of entities into Kong Gateway can be done in two ways: at start-up, through the <code class="language-plaintext highlighter-rouge">declarative_config</code> property, or at run-time, through the Admin API using the <code class="language-plaintext highlighter-rouge">/config</code> 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: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>kong config init </code></pre></div></div> It generates a file named <code class="language-plaintext highlighter-rouge">kong.yml</code> in the current directory, containing the appropriate structure and examples. <h3 id="reload-declarative-configuration">Reload Declarative Configuration</h3> 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 <a href="../reference/db-less-and-declarative-config">declarative configuration</a> documentation. <div class="endpoint post indent">/config</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> required </td> <td>The config data (in YAML or JSON format) to be loaded.</td> </tr> </tbody> </table> <h4 id="request-querystring-parameters">Request Querystring Parameters</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">check_hash</code> optional </td> <td>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.</td> </tr> </tbody> </table> <h4 id="response">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ { "services": [], "routes": [] } } </code></pre></div></div> The response contains a list of all the entities that were parsed from the input file. <hr> <h2 id="supported-content-types">Supported Content Types</h2> The Admin API accepts 3 content types on every endpoint: <ul> <li>application/json</li> </ul> Handy for complex bodies (ex: complex plugin configuration), in that case simply send a JSON representation of the data you want to send. Example: <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "config": { "limit": 10, "period": "seconds" } } </code></pre></div></div> An example adding a Route to a Service named <code class="language-plaintext highlighter-rouge">test-service</code>: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X POST http://localhost:8001/services/test-service/routes \ -H "Content-Type: application/json" \ -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ]}' </code></pre></div></div> <ul> <li>application/x-www-form-urlencoded</li> </ul> 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: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>config.limit=10&config.period=seconds </code></pre></div></div> 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 <code class="language-plaintext highlighter-rouge">test-service</code>: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X POST http://localhost:8001/services/test-service/routes \ -d "name=test-route" \ -d "paths[1]=/path/one" \ -d "paths[2]=/path/two" </code></pre></div></div> The following two examples are identical to the one above, but less explicit: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X POST http://localhost:8001/services/test-service/routes \ -d "name=test-route" \ -d "paths[]=/path/one" \ -d "paths[]=/path/two" curl -i -X POST http://localhost:8001/services/test-service/routes \ -d "name=test-route" \ -d "paths=/path/one" \ -d "paths=/path/two" </code></pre></div></div> <ul> <li>multipart/form-data</li> </ul> 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: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \ -F "name=pre-function" \ -F "config.access=@custom-auth.lua" </code></pre></div></div> When specifying arrays for this content-type, the array indices must be specified. An example Route added to a Service named <code class="language-plaintext highlighter-rouge">test-service</code>: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X POST http://localhost:8001/services/test-service/routes \ -F "name=test-route" \ -F "paths[1]=/path/one" \ -F "paths[2]=/path/two" </code></pre></div></div> <hr> <h2 class="badge enterprise" id="using-the-api-in-workspaces">Using the API in workspaces</h2> Any requests that don’t specify a workspace target the <code class="language-plaintext highlighter-rouge">default</code> workspace. To target a different workspace, prefix any endpoint with the workspace name or ID: <div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>http://localhost:8001/<WORKSPACE_NAME|ID>/<ENDPOINT> </code></pre></div></div> For example, if you don’t specify a workspace, this request retrieves a list of services from the <code class="language-plaintext highlighter-rouge">default</code> workspace: <div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X GET http://localhost:8001/services </code></pre></div></div> While this request retrieves all services from the workspace <code class="language-plaintext highlighter-rouge">SRE</code>: <div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -i -X GET http://localhost:8001/SRE/services </code></pre></div></div> <hr> <h2 id="information-routes">Information Routes</h2> <h3 class="badge dbless" id="retrieve-node-information">Retrieve Node Information</h3> Retrieve generic details about a node. <div class="endpoint get">/</div> <h4 id="response-1">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "hostname": "", "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969", "lua_version": "LuaJIT 2.1.0-beta3", "plugins": { "available_on_server": [ ... ], "enabled_in_cluster": [ ... ] }, "configuration" : { ... }, "tagline": "Welcome to Kong", "version": "0.14.0" } </code></pre></div></div> <ul> <li> <code class="language-plaintext highlighter-rouge">node_id</code>: A UUID representing the running Kong node. This UUID is randomly generated when Kong starts, so the node will have a different <code class="language-plaintext highlighter-rouge">node_id</code> each time it is restarted.</li> <li> <code class="language-plaintext highlighter-rouge">available_on_server</code>: Names of plugins that are installed on the node.</li> <li> <code class="language-plaintext highlighter-rouge">enabled_in_cluster</code>: Names of plugins that are enabled/configured. That is, the plugins configurations currently in the datastore shared by all Kong nodes.</li> </ul> <hr> <h3 class="badge dbless" id="check-endpoint-or-entity-existence">Check Endpoint Or Entity Existence</h3> Similar to <code class="language-plaintext highlighter-rouge">HTTP GET</code>, but does not return the body. Returns <code class="language-plaintext highlighter-rouge">HTTP 200</code> when the endpoint exits or <code class="language-plaintext highlighter-rouge">HTTP 404</code> when it does not. Other status codes are possible. <div class="endpoint head">/<any-endpoint></div> <h4 id="response-2">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Access-Control-Allow-Origin: * Content-Length: 11389 Content-Type: application/json; charset=utf-8 X-Kong-Admin-Latency: 1 </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-http-methods-by-endpoint">List Http Methods by Endpoint</h3> List all the supported <code class="language-plaintext highlighter-rouge">HTTP</code> methods by an endpoint. This can also be used with a <code class="language-plaintext highlighter-rouge">CORS</code> preflight request. <div class="endpoint options">/<any-endpoint></div> <h4 id="response-3">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Access-Control-Allow-Headers: Content-Type Access-Control-Allow-Methods: GET, HEAD, OPTIONS Access-Control-Allow-Origin: * Allow: GET, HEAD, OPTIONS </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-available-endpoints">List Available Endpoints</h3> List all available endpoints provided by the Admin API. <div class="endpoint get">/endpoints</div> <h4 id="response-4">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [ "/", "/acls", "/acls/{acls}", "/acls/{acls}/consumer", "/basic-auths", "/basic-auths/{basicauth_credentials}", "/basic-auths/{basicauth_credentials}/consumer", "/ca_certificates", "/ca_certificates/{ca_certificates}", "/cache", "/cache/{key}", "..." ] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="validate-a-configuration-against-a-schema">Validate A Configuration against A Schema</h3> 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. <div class="endpoint post">/schemas/{entity}/validate</div> <h4 id="response-5">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "message": "schema validation successful" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-entity-schema">Retrieve Entity Schema</h3> 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. <div class="endpoint get">/schemas/{entity name}</div> <h4 id="response-6">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "fields": [ { "id": { "auto": true, "type": "string", "uuid": true } }, { "created_at": { "auto": true, "timestamp": true, "type": "integer" } }, ... ] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-plugin-schema">Retrieve Plugin Schema</h3> 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. <div class="endpoint get">/schemas/plugins/{plugin name}</div> <h4 id="response-7">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "fields": { "hide_credentials": { "default": false, "type": "boolean" }, "key_names": { "default": "function", "required": true, "type": "array" } } } </code></pre></div></div> <hr> <h3 class="badge dbless" id="validate-a-plugin-configuration-against-the-schema">Validate A Plugin Configuration against The Schema</h3> 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. <div class="endpoint post">/schemas/plugins/validate</div> <h4 id="response-8">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "message": "schema validation successful" } </code></pre></div></div> <hr> <h2 id="health-routes">Health Routes</h2> <h3 class="badge dbless" id="retrieve-node-status">Retrieve Node Status</h3> 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. <div class="endpoint get">/status</div> <h4 id="response-9">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "database": { "reachable": true }, "memory": { "workers_lua_vms": [{ "http_allocated_gc": "0.02 MiB", "pid": 18477 }, { "http_allocated_gc": "0.02 MiB", "pid": 18478 }], "lua_shared_dicts": { "kong": { "allocated_slabs": "0.04 MiB", "capacity": "5.00 MiB" }, "kong_db_cache": { "allocated_slabs": "0.80 MiB", "capacity": "128.00 MiB" }, } }, "server": { "total_requests": 3, "connections_active": 1, "connections_accepted": 1, "connections_handled": 1, "connections_reading": 0, "connections_writing": 1, "connections_waiting": 0 } } </code></pre></div></div> <ul> <li> <code class="language-plaintext highlighter-rouge">memory</code>: Metrics about the memory usage. <ul> <li> <code class="language-plaintext highlighter-rouge">workers_lua_vms</code>: An array with all workers of the Kong node, where each entry contains:</li> <li> <code class="language-plaintext highlighter-rouge">http_allocated_gc</code>: HTTP submodule’s Lua virtual machine’s memory usage information, as reported by <code class="language-plaintext highlighter-rouge">collectgarbage("count")</code>, for every active worker, i.e. a worker that received a proxy call in the last 10 seconds.</li> <li> <code class="language-plaintext highlighter-rouge">pid</code>: worker’s process identification number.</li> <li> <code class="language-plaintext highlighter-rouge">lua_shared_dicts</code>: 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 (<code class="language-plaintext highlighter-rouge">capacity</code>) and how much of said memory is in use (<code class="language-plaintext highlighter-rouge">allocated_slabs</code>). These shared dictionaries have least recent used (LRU) eviction capabilities, so a full dictionary, where <code class="language-plaintext highlighter-rouge">allocated_slabs == capacity</code>, 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.</li> <li>The memory usage unit and precision can be changed using the querystring arguments <code class="language-plaintext highlighter-rouge">unit</code> and <code class="language-plaintext highlighter-rouge">scale</code>: <ul> <li> <code class="language-plaintext highlighter-rouge">unit</code>: one of <code class="language-plaintext highlighter-rouge">b/B</code>, <code class="language-plaintext highlighter-rouge">k/K</code>, <code class="language-plaintext highlighter-rouge">m/M</code>, <code class="language-plaintext highlighter-rouge">g/G</code>, 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 <code class="language-plaintext highlighter-rouge">m</code>.</li> <li> <code class="language-plaintext highlighter-rouge">scale</code>: 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 <code class="language-plaintext highlighter-rouge">2</code>. You can get the shared dictionaries memory usage in kibibytes with 4 digits of precision by doing: <code class="language-plaintext highlighter-rouge">GET /status?unit=k&scale=4</code> </li> </ul> </li> </ul> </li> <li> <code class="language-plaintext highlighter-rouge">server</code>: Metrics about the nginx HTTP/S server. <ul> <li> <code class="language-plaintext highlighter-rouge">total_requests</code>: The total number of client requests.</li> <li> <code class="language-plaintext highlighter-rouge">connections_active</code>: The current number of active client connections including Waiting connections.</li> <li> <code class="language-plaintext highlighter-rouge">connections_accepted</code>: The total number of accepted client connections.</li> <li> <code class="language-plaintext highlighter-rouge">connections_handled</code>: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.</li> <li> <code class="language-plaintext highlighter-rouge">connections_reading</code>: The current number of connections where Kong is reading the request header.</li> <li> <code class="language-plaintext highlighter-rouge">connections_writing</code>: The current number of connections where nginx is writing the response back to the client.</li> <li> <code class="language-plaintext highlighter-rouge">connections_waiting</code>: The current number of idle client connections waiting for a request.</li> </ul> </li> <li> <code class="language-plaintext highlighter-rouge">database</code>: Metrics about the database. <ul> <li> <code class="language-plaintext highlighter-rouge">reachable</code>: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself.</li> </ul> </li> </ul> <hr> <h2 id="tags">Tags</h2> Tags are strings associated to entities in Kong. Tags can contain almost all UTF-8 characters, with the following exceptions: <ul> <li> <code class="language-plaintext highlighter-rouge">,</code> and <code class="language-plaintext highlighter-rouge">/</code> are reserved for filtering tags with “and” and “or”, so they are not allowed in tags.</li> <li>Non-printable ASCII (for example, the space character) is not allowed.</li> </ul> Most core entities can be tagged via their <code class="language-plaintext highlighter-rouge">tags</code> attribute, upon creation or edition. Tags can be used to filter core entities as well, via the <code class="language-plaintext highlighter-rouge">?tags</code> querystring parameter. For example: if you normally get a list of all the Services by doing: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /services </code></pre></div></div> You can get the list of all the Services tagged <code class="language-plaintext highlighter-rouge">example</code> by doing: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /services?tags=example </code></pre></div></div> Similarly, if you want to filter Services so that you only get the ones tagged <code class="language-plaintext highlighter-rouge">example</code> and <code class="language-plaintext highlighter-rouge">admin</code>, you can do that like so: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /services?tags=example,admin </code></pre></div></div> Finally, if you wanted to filter the Services tagged <code class="language-plaintext highlighter-rouge">example</code> or <code class="language-plaintext highlighter-rouge">admin</code>, you could use: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /services?tags=example/admin </code></pre></div></div> Some notes: <ul> <li>A maximum of 5 tags can be queried simultaneously in a single request with <code class="language-plaintext highlighter-rouge">,</code> or <code class="language-plaintext highlighter-rouge">/</code> </li> <li>Mixing operators is not supported: if you try to mix <code class="language-plaintext highlighter-rouge">,</code> with <code class="language-plaintext highlighter-rouge">/</code> in the same querystring, you will receive an error.</li> <li>You may need to quote and/or escape some characters when using them from the command line.</li> <li>Filtering by <code class="language-plaintext highlighter-rouge">tags</code> is not supported in foreign key relationship endpoints. For example, the <code class="language-plaintext highlighter-rouge">tags</code> parameter will be ignored in a request such as <code class="language-plaintext highlighter-rouge">GET /services/foo/routes?tags=a,b</code> </li> <li> <code class="language-plaintext highlighter-rouge">offset</code> parameters are not guaranteed to work if the <code class="language-plaintext highlighter-rouge">tags</code> parameter is altered or removed</li> </ul> <h3 class="badge dbless" id="list-all-tags">List All Tags</h3> 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 <code class="language-plaintext highlighter-rouge">entity_id</code> 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. <div class="endpoint get">/tags</div> <h4 id="response-10">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ { "data": [ { "entity_name": "services", "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4", "tag": "s1", }, { "entity_name": "services", "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4", "tag": "s2", }, { "entity_name": "routes", "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000", "tag": "s1", }, ... ], "offset": "c47139f3-d780-483d-8a97-17e9adc5a7ab", "next": "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab", } } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-entity-ids-by-tag">List Entity Ids by Tag</h3> 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. <div class="endpoint get">/tags/{tags}</div> <h4 id="response-11">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ { "data": [ { "entity_name": "services", "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c", "tag": "example", }, { "entity_name": "routes", "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1", "tag": "example", }, ... ], "offset": "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9", "next": "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9", } } </code></pre></div></div> <hr> <h2 id="service-object">Service Object</h2> 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 <code class="language-plaintext highlighter-rouge">protocol</code>, <code class="language-plaintext highlighter-rouge">host</code>, <code class="language-plaintext highlighter-rouge">port</code> and <code class="language-plaintext highlighter-rouge">path</code> 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 <a href="/gateway/2.8.x/reference/proxy">Proxy Reference</a> for a detailed explanation of how Kong proxies traffic. Services can be both <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "9748f662-7711-4a90-8186-dc02f10eb0f5", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-service", "retries": 5, "protocol": "http", "host": "example.com", "port": 80, "path": "/some_api", "connect_timeout": 60000, "write_timeout": 60000, "read_timeout": 60000, "tags": ["user-level", "low-priority"], "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"}, "tls_verify": true, "tls_verify_depth": null, "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"], "enabled": true } </code></pre></div></div> <h3 id="add-service">Add Service</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-service">Create Service</h5> <div class="endpoint post indent">/services</div> <h5 id="create-service-associated-to-a-specific-certificate">Create Service Associated to a Specific Certificate</h5> <div class="endpoint post indent">/certificates/{certificate name or id}/services</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Certificate that should be associated to the newly-created Service.</td> </tr> </tbody> </table> <h4 id="request-body">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name</code> optional </td> <td>The Service name.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">retries</code> optional </td> <td>The number of retries to execute upon failure to proxy. Default: <code class="language-plaintext highlighter-rouge">5</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocol</code></td> <td>The protocol used to communicate with the upstream. Accepted values are: <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"tls"</code>, <code class="language-plaintext highlighter-rouge">"tls_passthrough"</code>, <code class="language-plaintext highlighter-rouge">"udp"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">host</code></td> <td>The host of the upstream server. Note that the host value is case sensitive.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">port</code></td> <td>The upstream server port. Default: <code class="language-plaintext highlighter-rouge">80</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">path</code> optional </td> <td>The path to be used in requests to the upstream server.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">connect_timeout</code> optional </td> <td>The timeout in milliseconds for establishing a connection to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">write_timeout</code> optional </td> <td>The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">read_timeout</code> optional </td> <td>The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Service for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">client_certificate</code> optional </td> <td>Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">client_certificate.id=<client_certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"client_certificate":{"id":"<client_certificate id>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tls_verify</code> optional </td> <td>Whether to enable verification of upstream server TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code>, then the Nginx default is respected.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tls_verify_depth</code> optional </td> <td>Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code>, then the Nginx default is respected. Default: <code class="language-plaintext highlighter-rouge">null</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificates</code> optional </td> <td>Array of <code class="language-plaintext highlighter-rouge">CA Certificate</code> object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code> 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 <code class="language-plaintext highlighter-rouge">ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">enabled</code></td> <td>Whether the Service is active. If set to <code class="language-plaintext highlighter-rouge">false</code>, the proxy behavior will be as if any routes attached to it do not exist (404). Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">url</code> shorthand-attribute </td> <td>Shorthand attribute to set <code class="language-plaintext highlighter-rouge">protocol</code>, <code class="language-plaintext highlighter-rouge">host</code>, <code class="language-plaintext highlighter-rouge">port</code> and <code class="language-plaintext highlighter-rouge">path</code> at once. This attribute is write-only (the Admin API never returns the URL).</td> </tr> </tbody> </table> <h4 id="response-12">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "9748f662-7711-4a90-8186-dc02f10eb0f5", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-service", "retries": 5, "protocol": "http", "host": "example.com", "port": 80, "path": "/some_api", "connect_timeout": 60000, "write_timeout": 60000, "read_timeout": 60000, "tags": ["user-level", "low-priority"], "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"}, "tls_verify": true, "tls_verify_depth": null, "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"], "enabled": true } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-services">List Services</h3> <h5 id="list-all-services">List All Services</h5> <div class="endpoint get indent">/services</div> <h5 id="list-services-associated-to-a-specific-certificate">List Services Associated to a Specific Certificate</h5> <div class="endpoint get indent">/certificates/{certificate name or id}/services</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Certificate whose Services are to be retrieved. When using this endpoint, only Services associated to the specified Certificate will be listed.</td> </tr> </tbody> </table> <h4 id="response-13">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-service", "retries": 5, "protocol": "http", "host": "example.com", "port": 80, "path": "/some_api", "connect_timeout": 60000, "write_timeout": 60000, "read_timeout": 60000, "tags": ["user-level", "low-priority"], "client_certificate": {"id":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"}, "tls_verify": true, "tls_verify_depth": null, "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"], "enabled": true }, { "id": "fc73f2af-890d-4f9b-8363-af8945001f7f", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-service", "retries": 5, "protocol": "http", "host": "example.com", "port": 80, "path": "/another_api", "connect_timeout": 60000, "write_timeout": 60000, "read_timeout": 60000, "tags": ["admin", "high-priority", "critical"], "client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"}, "tls_verify": true, "tls_verify_depth": null, "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"], "enabled": true }], "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-service">Retrieve Service</h3> <h5 id="retrieve-service-1">Retrieve Service</h5> <div class="endpoint get indent">/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-service-associated-to-a-specific-certificate">Retrieve Service Associated to a Specific Certificate</h5> <div class="endpoint get indent">/certificates/{certificate id}/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-service-associated-to-a-specific-route">Retrieve Service Associated to a Specific Route</h5> <div class="endpoint get indent">/routes/{route name or id}/service</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route associated to the Service to be retrieved.</td> </tr> </tbody> </table> <h5 id="retrieve-service-associated-to-a-specific-plugin">Retrieve Service Associated to a Specific Plugin</h5> <div class="endpoint get indent">/plugins/{plugin id}/service</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Service to be retrieved.</td> </tr> </tbody> </table> <h4 id="response-14">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "9748f662-7711-4a90-8186-dc02f10eb0f5", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-service", "retries": 5, "protocol": "http", "host": "example.com", "port": 80, "path": "/some_api", "connect_timeout": 60000, "write_timeout": 60000, "read_timeout": 60000, "tags": ["user-level", "low-priority"], "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"}, "tls_verify": true, "tls_verify_depth": null, "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"], "enabled": true } </code></pre></div></div> <hr> <h3 id="update-service">Update Service</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-service-1">Update Service</h5> <div class="endpoint patch indent">/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to update.</td> </tr> </tbody> </table> <h5 id="update-service-associated-to-a-specific-certificate">Update Service Associated to a Specific Certificate</h5> <div class="endpoint patch indent">/certificates/{certificate id}/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to update.</td> </tr> </tbody> </table> <h5 id="update-service-associated-to-a-specific-route">Update Service Associated to a Specific Route</h5> <div class="endpoint patch indent">/routes/{route name or id}/service</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route associated to the Service to be updated.</td> </tr> </tbody> </table> <h5 id="update-service-associated-to-a-specific-plugin">Update Service Associated to a Specific Plugin</h5> <div class="endpoint patch indent">/plugins/{plugin id}/service</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Service to be updated.</td> </tr> </tbody> </table> <h4 id="request-body-1">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name</code> optional </td> <td>The Service name.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">retries</code> optional </td> <td>The number of retries to execute upon failure to proxy. Default: <code class="language-plaintext highlighter-rouge">5</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocol</code></td> <td>The protocol used to communicate with the upstream. Accepted values are: <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"tls"</code>, <code class="language-plaintext highlighter-rouge">"tls_passthrough"</code>, <code class="language-plaintext highlighter-rouge">"udp"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">host</code></td> <td>The host of the upstream server. Note that the host value is case sensitive.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">port</code></td> <td>The upstream server port. Default: <code class="language-plaintext highlighter-rouge">80</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">path</code> optional </td> <td>The path to be used in requests to the upstream server.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">connect_timeout</code> optional </td> <td>The timeout in milliseconds for establishing a connection to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">write_timeout</code> optional </td> <td>The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">read_timeout</code> optional </td> <td>The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Service for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">client_certificate</code> optional </td> <td>Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">client_certificate.id=<client_certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"client_certificate":{"id":"<client_certificate id>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tls_verify</code> optional </td> <td>Whether to enable verification of upstream server TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code>, then the Nginx default is respected.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tls_verify_depth</code> optional </td> <td>Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code>, then the Nginx default is respected. Default: <code class="language-plaintext highlighter-rouge">null</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificates</code> optional </td> <td>Array of <code class="language-plaintext highlighter-rouge">CA Certificate</code> object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code> 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 <code class="language-plaintext highlighter-rouge">ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">enabled</code></td> <td>Whether the Service is active. If set to <code class="language-plaintext highlighter-rouge">false</code>, the proxy behavior will be as if any routes attached to it do not exist (404). Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">url</code> shorthand-attribute </td> <td>Shorthand attribute to set <code class="language-plaintext highlighter-rouge">protocol</code>, <code class="language-plaintext highlighter-rouge">host</code>, <code class="language-plaintext highlighter-rouge">port</code> and <code class="language-plaintext highlighter-rouge">path</code> at once. This attribute is write-only (the Admin API never returns the URL).</td> </tr> </tbody> </table> <h4 id="response-15">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "9748f662-7711-4a90-8186-dc02f10eb0f5", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-service", "retries": 5, "protocol": "http", "host": "example.com", "port": 80, "path": "/some_api", "connect_timeout": 60000, "write_timeout": 60000, "read_timeout": 60000, "tags": ["user-level", "low-priority"], "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"}, "tls_verify": true, "tls_verify_depth": null, "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"], "enabled": true } </code></pre></div></div> <hr> <h3 id="update-or-create-service">Update Or Create Service</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-service">Create Or Update Service</h5> <div class="endpoint put indent">/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-service-associated-to-a-specific-certificate">Create Or Update Service Associated to a Specific Certificate</h5> <div class="endpoint put indent">/certificates/{certificate id}/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-service-associated-to-a-specific-route">Create Or Update Service Associated to a Specific Route</h5> <div class="endpoint put indent">/routes/{route name or id}/service</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route associated to the Service to be created or updated.</td> </tr> </tbody> </table> <h5 id="create-or-update-service-associated-to-a-specific-plugin">Create Or Update Service Associated to a Specific Plugin</h5> <div class="endpoint put indent">/plugins/{plugin id}/service</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Service to be created or updated.</td> </tr> </tbody> </table> <h4 id="request-body-2">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name</code> optional </td> <td>The Service name.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">retries</code> optional </td> <td>The number of retries to execute upon failure to proxy. Default: <code class="language-plaintext highlighter-rouge">5</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocol</code></td> <td>The protocol used to communicate with the upstream. Accepted values are: <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"tls"</code>, <code class="language-plaintext highlighter-rouge">"tls_passthrough"</code>, <code class="language-plaintext highlighter-rouge">"udp"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">host</code></td> <td>The host of the upstream server. Note that the host value is case sensitive.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">port</code></td> <td>The upstream server port. Default: <code class="language-plaintext highlighter-rouge">80</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">path</code> optional </td> <td>The path to be used in requests to the upstream server.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">connect_timeout</code> optional </td> <td>The timeout in milliseconds for establishing a connection to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">write_timeout</code> optional </td> <td>The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">read_timeout</code> optional </td> <td>The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: <code class="language-plaintext highlighter-rouge">60000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Service for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">client_certificate</code> optional </td> <td>Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">client_certificate.id=<client_certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"client_certificate":{"id":"<client_certificate id>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tls_verify</code> optional </td> <td>Whether to enable verification of upstream server TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code>, then the Nginx default is respected.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tls_verify_depth</code> optional </td> <td>Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code>, then the Nginx default is respected. Default: <code class="language-plaintext highlighter-rouge">null</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificates</code> optional </td> <td>Array of <code class="language-plaintext highlighter-rouge">CA Certificate</code> object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to <code class="language-plaintext highlighter-rouge">null</code> 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 <code class="language-plaintext highlighter-rouge">ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">enabled</code></td> <td>Whether the Service is active. If set to <code class="language-plaintext highlighter-rouge">false</code>, the proxy behavior will be as if any routes attached to it do not exist (404). Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">url</code> shorthand-attribute </td> <td>Shorthand attribute to set <code class="language-plaintext highlighter-rouge">protocol</code>, <code class="language-plaintext highlighter-rouge">host</code>, <code class="language-plaintext highlighter-rouge">port</code> and <code class="language-plaintext highlighter-rouge">path</code> at once. This attribute is write-only (the Admin API never returns the URL).</td> </tr> </tbody> </table> Inserts (or replaces) the Service under the requested resource with the definition specified in the body. The Service will be identified via the <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the Service being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new Service without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-16">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-service">Delete Service</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-service-1">Delete Service</h5> <div class="endpoint delete indent">/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to delete.</td> </tr> </tbody> </table> <h5 id="delete-service-associated-to-a-specific-certificate">Delete Service Associated to a Specific Certificate</h5> <div class="endpoint delete indent">/certificates/{certificate id}/services/{service name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to delete.</td> </tr> </tbody> </table> <h4 id="response-17">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h2 id="route-object">Route Object</h2> 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 <code class="language-plaintext highlighter-rouge">protocols</code> field), this means that at least one of the following attributes must be set: <ul> <li>For <code class="language-plaintext highlighter-rouge">http</code>, at least one of <code class="language-plaintext highlighter-rouge">methods</code>, <code class="language-plaintext highlighter-rouge">hosts</code>, <code class="language-plaintext highlighter-rouge">headers</code> or <code class="language-plaintext highlighter-rouge">paths</code>;</li> <li>For <code class="language-plaintext highlighter-rouge">https</code>, at least one of <code class="language-plaintext highlighter-rouge">methods</code>, <code class="language-plaintext highlighter-rouge">hosts</code>, <code class="language-plaintext highlighter-rouge">headers</code>, <code class="language-plaintext highlighter-rouge">paths</code> or <code class="language-plaintext highlighter-rouge">snis</code>;</li> <li>For <code class="language-plaintext highlighter-rouge">tcp</code>, at least one of <code class="language-plaintext highlighter-rouge">sources</code> or <code class="language-plaintext highlighter-rouge">destinations</code>;</li> <li>For <code class="language-plaintext highlighter-rouge">tls</code>, at least one of <code class="language-plaintext highlighter-rouge">sources</code>, <code class="language-plaintext highlighter-rouge">destinations</code> or <code class="language-plaintext highlighter-rouge">snis</code>;</li> <li>For <code class="language-plaintext highlighter-rouge">tls_passthrough</code>, set <code class="language-plaintext highlighter-rouge">snis</code>;</li> <li>For <code class="language-plaintext highlighter-rouge">grpc</code>, at least one of <code class="language-plaintext highlighter-rouge">hosts</code>, <code class="language-plaintext highlighter-rouge">headers</code> or <code class="language-plaintext highlighter-rouge">paths</code>;</li> <li>For <code class="language-plaintext highlighter-rouge">grpcs</code>, at least one of <code class="language-plaintext highlighter-rouge">hosts</code>, <code class="language-plaintext highlighter-rouge">headers</code>, <code class="language-plaintext highlighter-rouge">paths</code> or <code class="language-plaintext highlighter-rouge">snis</code>.</li> </ul> A route can’t have both <code class="language-plaintext highlighter-rouge">tls</code> and <code class="language-plaintext highlighter-rouge">tls_passthrough</code> protocols at same time. <h4 id="path-handling-algorithms">Path handling algorithms</h4> <code class="language-plaintext highlighter-rouge">"v0"</code> is the behavior used in Kong 0.x and 2.x. It treats <code class="language-plaintext highlighter-rouge">service.path</code>, <code class="language-plaintext highlighter-rouge">route.path</code> and request path as segments of a URL. It will always join them via slashes. Given a service path <code class="language-plaintext highlighter-rouge">/s</code>, route path <code class="language-plaintext highlighter-rouge">/r</code> and request path <code class="language-plaintext highlighter-rouge">/re</code>, the concatenated path will be <code class="language-plaintext highlighter-rouge">/s/re</code>. 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. <code class="language-plaintext highlighter-rouge">"v1"</code> is the behavior used in Kong 1.x. It treats <code class="language-plaintext highlighter-rouge">service.path</code> as a prefix, and ignores the initial slashes of the request and route paths. Given service path <code class="language-plaintext highlighter-rouge">/s</code>, route path <code class="language-plaintext highlighter-rouge">/r</code> and request path <code class="language-plaintext highlighter-rouge">/re</code>, the concatenated path will be <code class="language-plaintext highlighter-rouge">/sre</code>. 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: <table> <thead> <tr> <th><code class="language-plaintext highlighter-rouge">service.path</code></th> <th><code class="language-plaintext highlighter-rouge">route.path</code></th> <th><code class="language-plaintext highlighter-rouge">request</code></th> <th><code class="language-plaintext highlighter-rouge">route.strip_path</code></th> <th><code class="language-plaintext highlighter-rouge">route.path_handling</code></th> <th>request path</th> <th>upstream path</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0/req</code></td> <td><code class="language-plaintext highlighter-rouge">/s/fv0/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0</code></td> <td><code class="language-plaintext highlighter-rouge">/s/fv0</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1/req</code></td> <td><code class="language-plaintext highlighter-rouge">/sfv1/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1</code></td> <td><code class="language-plaintext highlighter-rouge">/sfv1</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0/req</code></td> <td><code class="language-plaintext highlighter-rouge">/s/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0</code></td> <td><code class="language-plaintext highlighter-rouge">/s</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1/req</code></td> <td><code class="language-plaintext highlighter-rouge">/s/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1</code></td> <td><code class="language-plaintext highlighter-rouge">/s</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0/</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0/req</code></td> <td><code class="language-plaintext highlighter-rouge">/s/fv0/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0/</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/fv0/</code></td> <td><code class="language-plaintext highlighter-rouge">/s/fv01/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1/</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1/req</code></td> <td><code class="language-plaintext highlighter-rouge">/sfv1/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1/</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/fv1/</code></td> <td><code class="language-plaintext highlighter-rouge">/sfv1/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0/</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0/req</code></td> <td><code class="language-plaintext highlighter-rouge">/s/req</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0/</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v0</code></td> <td><code class="language-plaintext highlighter-rouge">/tv0/</code></td> <td><code class="language-plaintext highlighter-rouge">/s/</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1/</code></td> <td><code class="language-plaintext highlighter-rouge">req</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1/req</code></td> <td><code class="language-plaintext highlighter-rouge">/sreq</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/s</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1/</code></td> <td><code class="language-plaintext highlighter-rouge">blank</code></td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td><code class="language-plaintext highlighter-rouge">v1</code></td> <td><code class="language-plaintext highlighter-rouge">/tv1/</code></td> <td><code class="language-plaintext highlighter-rouge">/s</code></td> </tr> </tbody> </table> Routes can be both <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-route", "protocols": ["http", "https"], "methods": ["GET", "POST"], "hosts": ["example.com", "foo.test"], "paths": ["/foo", "/bar"], "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]}, "https_redirect_status_code": 426, "regex_priority": 0, "strip_path": true, "path_handling": "v0", "preserve_host": false, "request_buffering": true, "response_buffering": true, "tags": ["user-level", "low-priority"], "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"} } </code></pre></div></div> <h3 id="add-route">Add Route</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-route">Create Route</h5> <div class="endpoint post indent">/routes</div> <h5 id="create-route-associated-to-a-specific-service">Create Route Associated to a Specific Service</h5> <div class="endpoint post indent">/services/{service name or id}/routes</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Service that should be associated to the newly-created Route.</td> </tr> </tbody> </table> <h4 id="request-body-3">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name</code> optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocols</code></td> <td>An array of the protocols this Route should allow. See the <a href="#route-object">Route Object</a> section for a list of accepted protocols. When set to only <code class="language-plaintext highlighter-rouge">"https"</code>, HTTP requests are answered with an upgrade error. When set to only <code class="language-plaintext highlighter-rouge">"http"</code>, HTTPS requests are answered with an error. Default: <code class="language-plaintext highlighter-rouge">["http", "https"]</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">methods</code> semi-optional </td> <td>A list of HTTP methods that match this Route.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hosts</code> semi-optional </td> <td>A list of domain names that match this Route. Note that the hosts value is case sensitive. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">hosts[]=example.com&hosts[]=foo.test</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">paths</code> semi-optional </td> <td>A list of paths that match this Route. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">paths[]=/foo&paths[]=/bar</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">headers</code> semi-optional </td> <td>One or more lists of values indexed by header name that will cause this Route to match if present in the request. The <code class="language-plaintext highlighter-rouge">Host</code> header cannot be used with this attribute: hosts should be specified using the <code class="language-plaintext highlighter-rouge">hosts</code> attribute.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">https_redirect_status_code</code></td> <td>The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is <code class="language-plaintext highlighter-rouge">HTTP</code> instead of <code class="language-plaintext highlighter-rouge">HTTPS</code>. <code class="language-plaintext highlighter-rouge">Location</code> header is injected by Kong if the field is set to 301, 302, 307 or 308. Accepted values are: <code class="language-plaintext highlighter-rouge">426</code>, <code class="language-plaintext highlighter-rouge">301</code>, <code class="language-plaintext highlighter-rouge">302</code>, <code class="language-plaintext highlighter-rouge">307</code>, <code class="language-plaintext highlighter-rouge">308</code>. Default: <code class="language-plaintext highlighter-rouge">426</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">regex_priority</code> optional </td> <td>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 <code class="language-plaintext highlighter-rouge">regex_priority</code>, the older one (lowest <code class="language-plaintext highlighter-rouge">created_at</code>) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">strip_path</code></td> <td>When matching a Route via one of the <code class="language-plaintext highlighter-rouge">paths</code>, strip the matching prefix from the upstream request URL. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">path_handling</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">"v0"</code>, <code class="language-plaintext highlighter-rouge">"v1"</code>. Default: <code class="language-plaintext highlighter-rouge">"v0"</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">preserve_host</code></td> <td>When matching a Route via one of the <code class="language-plaintext highlighter-rouge">hosts</code> domain names, use the request <code class="language-plaintext highlighter-rouge">Host</code> header in the upstream request headers. If set to <code class="language-plaintext highlighter-rouge">false</code>, the upstream <code class="language-plaintext highlighter-rouge">Host</code> header will be that of the Service’s <code class="language-plaintext highlighter-rouge">host</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">request_buffering</code></td> <td>Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">response_buffering</code></td> <td>Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">snis</code> semi-optional </td> <td>A list of SNIs that match this Route when using stream routing.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sources</code> semi-optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">destinations</code> semi-optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Route for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service</code> optional </td> <td>The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">service.id=<service id></code> or <code class="language-plaintext highlighter-rouge">service.name=<service name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"service":{"id":"<service id>"}</code> or <code class="language-plaintext highlighter-rouge">"service":{"name":"<service name>"}</code>.</td> </tr> </tbody> </table> <h4 id="response-18">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-route", "protocols": ["http", "https"], "methods": ["GET", "POST"], "hosts": ["example.com", "foo.test"], "paths": ["/foo", "/bar"], "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]}, "https_redirect_status_code": 426, "regex_priority": 0, "strip_path": true, "path_handling": "v0", "preserve_host": false, "request_buffering": true, "response_buffering": true, "tags": ["user-level", "low-priority"], "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"} } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-routes">List Routes</h3> <h5 id="list-all-routes">List All Routes</h5> <div class="endpoint get indent">/routes</div> <h5 id="list-routes-associated-to-a-specific-service">List Routes Associated to a Specific Service</h5> <div class="endpoint get indent">/services/{service name or id}/routes</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Service whose Routes are to be retrieved. When using this endpoint, only Routes associated to the specified Service will be listed.</td> </tr> </tbody> </table> <h4 id="response-19">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "a9daa3ba-8186-4a0d-96e8-00d80ce7240b", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-route", "protocols": ["http", "https"], "methods": ["GET", "POST"], "hosts": ["example.com", "foo.test"], "paths": ["/foo", "/bar"], "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]}, "https_redirect_status_code": 426, "regex_priority": 0, "strip_path": true, "path_handling": "v0", "preserve_host": false, "request_buffering": true, "response_buffering": true, "tags": ["user-level", "low-priority"], "service": {"id":"127dfc88-ed57-45bf-b77a-a9d3a152ad31"} }, { "id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-route", "protocols": ["tcp", "tls"], "https_redirect_status_code": 426, "regex_priority": 0, "strip_path": true, "path_handling": "v0", "preserve_host": false, "request_buffering": true, "response_buffering": true, "snis": ["foo.test", "example.com"], "sources": [{"port":1234, "ip":"10.1.0.0/16"}, {"ip":"10.2.2.2"}, {"port":9123}], "destinations": [{"port":1234, "ip":"10.1.0.0/16"}, {"ip":"10.2.2.2"}, {"port":9123}], "tags": ["admin", "high-priority", "critical"], "service": {"id":"ba641b07-e74a-430a-ab46-94b61e5ea66b"} }], "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-route">Retrieve Route</h3> <h5 id="retrieve-route-1">Retrieve Route</h5> <div class="endpoint get indent">/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-route-associated-to-a-specific-service">Retrieve Route Associated to a Specific Service</h5> <div class="endpoint get indent">/services/{service name or id}/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-route-associated-to-a-specific-plugin">Retrieve Route Associated to a Specific Plugin</h5> <div class="endpoint get indent">/plugins/{plugin id}/route</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Route to be retrieved.</td> </tr> </tbody> </table> <h4 id="response-20">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-route", "protocols": ["http", "https"], "methods": ["GET", "POST"], "hosts": ["example.com", "foo.test"], "paths": ["/foo", "/bar"], "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]}, "https_redirect_status_code": 426, "regex_priority": 0, "strip_path": true, "path_handling": "v0", "preserve_host": false, "request_buffering": true, "response_buffering": true, "tags": ["user-level", "low-priority"], "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"} } </code></pre></div></div> <hr> <h3 id="update-route">Update Route</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-route-1">Update Route</h5> <div class="endpoint patch indent">/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to update.</td> </tr> </tbody> </table> <h5 id="update-route-associated-to-a-specific-service">Update Route Associated to a Specific Service</h5> <div class="endpoint patch indent">/services/{service name or id}/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to update.</td> </tr> </tbody> </table> <h5 id="update-route-associated-to-a-specific-plugin">Update Route Associated to a Specific Plugin</h5> <div class="endpoint patch indent">/plugins/{plugin id}/route</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Route to be updated.</td> </tr> </tbody> </table> <h4 id="request-body-4">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name</code> optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocols</code></td> <td>An array of the protocols this Route should allow. See the <a href="#route-object">Route Object</a> section for a list of accepted protocols. When set to only <code class="language-plaintext highlighter-rouge">"https"</code>, HTTP requests are answered with an upgrade error. When set to only <code class="language-plaintext highlighter-rouge">"http"</code>, HTTPS requests are answered with an error. Default: <code class="language-plaintext highlighter-rouge">["http", "https"]</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">methods</code> semi-optional </td> <td>A list of HTTP methods that match this Route.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hosts</code> semi-optional </td> <td>A list of domain names that match this Route. Note that the hosts value is case sensitive. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">hosts[]=example.com&hosts[]=foo.test</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">paths</code> semi-optional </td> <td>A list of paths that match this Route. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">paths[]=/foo&paths[]=/bar</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">headers</code> semi-optional </td> <td>One or more lists of values indexed by header name that will cause this Route to match if present in the request. The <code class="language-plaintext highlighter-rouge">Host</code> header cannot be used with this attribute: hosts should be specified using the <code class="language-plaintext highlighter-rouge">hosts</code> attribute.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">https_redirect_status_code</code></td> <td>The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is <code class="language-plaintext highlighter-rouge">HTTP</code> instead of <code class="language-plaintext highlighter-rouge">HTTPS</code>. <code class="language-plaintext highlighter-rouge">Location</code> header is injected by Kong if the field is set to 301, 302, 307 or 308. Accepted values are: <code class="language-plaintext highlighter-rouge">426</code>, <code class="language-plaintext highlighter-rouge">301</code>, <code class="language-plaintext highlighter-rouge">302</code>, <code class="language-plaintext highlighter-rouge">307</code>, <code class="language-plaintext highlighter-rouge">308</code>. Default: <code class="language-plaintext highlighter-rouge">426</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">regex_priority</code> optional </td> <td>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 <code class="language-plaintext highlighter-rouge">regex_priority</code>, the older one (lowest <code class="language-plaintext highlighter-rouge">created_at</code>) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">strip_path</code></td> <td>When matching a Route via one of the <code class="language-plaintext highlighter-rouge">paths</code>, strip the matching prefix from the upstream request URL. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">path_handling</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">"v0"</code>, <code class="language-plaintext highlighter-rouge">"v1"</code>. Default: <code class="language-plaintext highlighter-rouge">"v0"</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">preserve_host</code></td> <td>When matching a Route via one of the <code class="language-plaintext highlighter-rouge">hosts</code> domain names, use the request <code class="language-plaintext highlighter-rouge">Host</code> header in the upstream request headers. If set to <code class="language-plaintext highlighter-rouge">false</code>, the upstream <code class="language-plaintext highlighter-rouge">Host</code> header will be that of the Service’s <code class="language-plaintext highlighter-rouge">host</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">request_buffering</code></td> <td>Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">response_buffering</code></td> <td>Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">snis</code> semi-optional </td> <td>A list of SNIs that match this Route when using stream routing.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sources</code> semi-optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">destinations</code> semi-optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Route for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service</code> optional </td> <td>The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">service.id=<service id></code> or <code class="language-plaintext highlighter-rouge">service.name=<service name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"service":{"id":"<service id>"}</code> or <code class="language-plaintext highlighter-rouge">"service":{"name":"<service name>"}</code>.</td> </tr> </tbody> </table> <h4 id="response-21">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe", "created_at": 1422386534, "updated_at": 1422386534, "name": "my-route", "protocols": ["http", "https"], "methods": ["GET", "POST"], "hosts": ["example.com", "foo.test"], "paths": ["/foo", "/bar"], "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]}, "https_redirect_status_code": 426, "regex_priority": 0, "strip_path": true, "path_handling": "v0", "preserve_host": false, "request_buffering": true, "response_buffering": true, "tags": ["user-level", "low-priority"], "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"} } </code></pre></div></div> <hr> <h3 id="update-or-create-route">Update Or Create Route</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-route">Create Or Update Route</h5> <div class="endpoint put indent">/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-route-associated-to-a-specific-service">Create Or Update Route Associated to a Specific Service</h5> <div class="endpoint put indent">/services/{service name or id}/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-route-associated-to-a-specific-plugin">Create Or Update Route Associated to a Specific Plugin</h5> <div class="endpoint put indent">/plugins/{plugin id}/route</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Route to be created or updated.</td> </tr> </tbody> </table> <h4 id="request-body-5">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name</code> optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocols</code></td> <td>An array of the protocols this Route should allow. See the <a href="#route-object">Route Object</a> section for a list of accepted protocols. When set to only <code class="language-plaintext highlighter-rouge">"https"</code>, HTTP requests are answered with an upgrade error. When set to only <code class="language-plaintext highlighter-rouge">"http"</code>, HTTPS requests are answered with an error. Default: <code class="language-plaintext highlighter-rouge">["http", "https"]</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">methods</code> semi-optional </td> <td>A list of HTTP methods that match this Route.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hosts</code> semi-optional </td> <td>A list of domain names that match this Route. Note that the hosts value is case sensitive. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">hosts[]=example.com&hosts[]=foo.test</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">paths</code> semi-optional </td> <td>A list of paths that match this Route. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">paths[]=/foo&paths[]=/bar</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">headers</code> semi-optional </td> <td>One or more lists of values indexed by header name that will cause this Route to match if present in the request. The <code class="language-plaintext highlighter-rouge">Host</code> header cannot be used with this attribute: hosts should be specified using the <code class="language-plaintext highlighter-rouge">hosts</code> attribute.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">https_redirect_status_code</code></td> <td>The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is <code class="language-plaintext highlighter-rouge">HTTP</code> instead of <code class="language-plaintext highlighter-rouge">HTTPS</code>. <code class="language-plaintext highlighter-rouge">Location</code> header is injected by Kong if the field is set to 301, 302, 307 or 308. Accepted values are: <code class="language-plaintext highlighter-rouge">426</code>, <code class="language-plaintext highlighter-rouge">301</code>, <code class="language-plaintext highlighter-rouge">302</code>, <code class="language-plaintext highlighter-rouge">307</code>, <code class="language-plaintext highlighter-rouge">308</code>. Default: <code class="language-plaintext highlighter-rouge">426</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">regex_priority</code> optional </td> <td>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 <code class="language-plaintext highlighter-rouge">regex_priority</code>, the older one (lowest <code class="language-plaintext highlighter-rouge">created_at</code>) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">strip_path</code></td> <td>When matching a Route via one of the <code class="language-plaintext highlighter-rouge">paths</code>, strip the matching prefix from the upstream request URL. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">path_handling</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">"v0"</code>, <code class="language-plaintext highlighter-rouge">"v1"</code>. Default: <code class="language-plaintext highlighter-rouge">"v0"</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">preserve_host</code></td> <td>When matching a Route via one of the <code class="language-plaintext highlighter-rouge">hosts</code> domain names, use the request <code class="language-plaintext highlighter-rouge">Host</code> header in the upstream request headers. If set to <code class="language-plaintext highlighter-rouge">false</code>, the upstream <code class="language-plaintext highlighter-rouge">Host</code> header will be that of the Service’s <code class="language-plaintext highlighter-rouge">host</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">request_buffering</code></td> <td>Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">response_buffering</code></td> <td>Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">snis</code> semi-optional </td> <td>A list of SNIs that match this Route when using stream routing.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sources</code> semi-optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">destinations</code> semi-optional </td> <td>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”.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Route for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service</code> optional </td> <td>The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">service.id=<service id></code> or <code class="language-plaintext highlighter-rouge">service.name=<service name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"service":{"id":"<service id>"}</code> or <code class="language-plaintext highlighter-rouge">"service":{"name":"<service name>"}</code>.</td> </tr> </tbody> </table> Inserts (or replaces) the Route under the requested resource with the definition specified in the body. The Route will be identified via the <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the Route being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new Route without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-22">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-route">Delete Route</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-route-1">Delete Route</h5> <div class="endpoint delete indent">/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to delete.</td> </tr> </tbody> </table> <h5 id="delete-route-associated-to-a-specific-service">Delete Route Associated to a Specific Service</h5> <div class="endpoint delete indent">/services/{service name or id}/routes/{route name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to delete.</td> </tr> </tbody> </table> <h4 id="response-23">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h2 id="consumer-object">Consumer Object</h2> The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore. Consumers can be both <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27", "created_at": 1422386534, "username": "my-username", "custom_id": "my-custom-id", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <h3 id="add-consumer">Add Consumer</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-consumer">Create Consumer</h5> <div class="endpoint post indent">/consumers</div> <h4 id="request-body-6">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">username</code> semi-optional </td> <td>The unique username of the Consumer. You must send either this field or <code class="language-plaintext highlighter-rouge">custom_id</code> with the request.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">custom_id</code> semi-optional </td> <td>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 <code class="language-plaintext highlighter-rouge">username</code> with the request.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Consumer for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-24">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27", "created_at": 1422386534, "username": "my-username", "custom_id": "my-custom-id", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-consumers">List Consumers</h3> <h5 id="list-all-consumers">List All Consumers</h5> <div class="endpoint get indent">/consumers</div> <h4 id="response-25">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7", "created_at": 1422386534, "username": "my-username", "custom_id": "my-custom-id", "tags": ["user-level", "low-priority"] }, { "id": "01c23299-839c-49a5-a6d5-8864c09184af", "created_at": 1422386534, "username": "my-username", "custom_id": "my-custom-id", "tags": ["admin", "high-priority", "critical"] }], "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-consumer">Retrieve Consumer</h3> <h5 id="retrieve-consumer-1">Retrieve Consumer</h5> <div class="endpoint get indent">/consumers/{consumer username or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-consumer-associated-to-a-specific-plugin">Retrieve Consumer Associated to a Specific Plugin</h5> <div class="endpoint get indent">/plugins/{plugin id}/consumer</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Consumer to be retrieved.</td> </tr> </tbody> </table> <h4 id="response-26">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27", "created_at": 1422386534, "username": "my-username", "custom_id": "my-custom-id", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-consumer">Update Consumer</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-consumer-1">Update Consumer</h5> <div class="endpoint patch indent">/consumers/{consumer username or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to update.</td> </tr> </tbody> </table> <h5 id="update-consumer-associated-to-a-specific-plugin">Update Consumer Associated to a Specific Plugin</h5> <div class="endpoint patch indent">/plugins/{plugin id}/consumer</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Consumer to be updated.</td> </tr> </tbody> </table> <h4 id="request-body-7">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">username</code> semi-optional </td> <td>The unique username of the Consumer. You must send either this field or <code class="language-plaintext highlighter-rouge">custom_id</code> with the request.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">custom_id</code> semi-optional </td> <td>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 <code class="language-plaintext highlighter-rouge">username</code> with the request.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Consumer for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-27">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27", "created_at": 1422386534, "username": "my-username", "custom_id": "my-custom-id", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-or-create-consumer">Update Or Create Consumer</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-consumer">Create Or Update Consumer</h5> <div class="endpoint put indent">/consumers/{consumer username or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-consumer-associated-to-a-specific-plugin">Create Or Update Consumer Associated to a Specific Plugin</h5> <div class="endpoint put indent">/plugins/{plugin id}/consumer</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin associated to the Consumer to be created or updated.</td> </tr> </tbody> </table> <h4 id="request-body-8">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">username</code> semi-optional </td> <td>The unique username of the Consumer. You must send either this field or <code class="language-plaintext highlighter-rouge">custom_id</code> with the request.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">custom_id</code> semi-optional </td> <td>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 <code class="language-plaintext highlighter-rouge">username</code> with the request.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Consumer for grouping and filtering.</td> </tr> </tbody> </table> Inserts (or replaces) the Consumer under the requested resource with the definition specified in the body. The Consumer will be identified via the <code class="language-plaintext highlighter-rouge">username or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">username or id</code> attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">username</code>. When creating a new Consumer without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">username</code> in the URL and a different one in the request body is not allowed. <h4 id="response-28">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-consumer">Delete Consumer</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-consumer-1">Delete Consumer</h5> <div class="endpoint delete indent">/consumers/{consumer username or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to delete.</td> </tr> </tbody> </table> <h4 id="response-29">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h2 id="plugin-object">Plugin Object</h2> 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 <a href="/hub/">Kong Hub</a>. 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 <code class="language-plaintext highlighter-rouge">service</code> and <code class="language-plaintext highlighter-rouge">consumer</code> fields. Plugins can be both <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7", "name": "rate-limiting", "created_at": 1422386534, "route": null, "service": null, "consumer": null, "config": {"minute":20, "hour":500}, "protocols": ["http", "https"], "enabled": true, "tags": ["user-level", "low-priority"] } </code></pre></div></div> See the <a href="#precedence">Precedence</a> section below for more details. <h4 id="precedence">Precedence</h4> 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: <ol> <li>Plugins configured on a combination of: a Route, a Service, and a Consumer. (Consumer means the request must be authenticated).</li> <li>Plugins configured on a combination of a Route and a Consumer. (Consumer means the request must be authenticated).</li> <li>Plugins configured on a combination of a Service and a Consumer. (Consumer means the request must be authenticated).</li> <li>Plugins configured on a combination of a Route and a Service.</li> <li>Plugins configured on a Consumer. (Consumer means the request must be authenticated).</li> <li>Plugins configured on a Route.</li> <li>Plugins configured on a Service.</li> <li>Plugins configured to run globally.</li> </ol> Example: if the <code class="language-plaintext highlighter-rouge">rate-limiting</code> 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 <code class="language-plaintext highlighter-rouge">enabled</code> flag is set to <code class="language-plaintext highlighter-rouge">false</code>), config A will apply to requests that would have otherwise matched config B. <h3 id="add-plugin">Add Plugin</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-plugin">Create Plugin</h5> <div class="endpoint post indent">/plugins</div> <h5 id="create-plugin-associated-to-a-specific-route">Create Plugin Associated to a Specific Route</h5> <div class="endpoint post indent">/routes/{route name or id}/plugins</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Route that should be associated to the newly-created Plugin.</td> </tr> </tbody> </table> <h5 id="create-plugin-associated-to-a-specific-service">Create Plugin Associated to a Specific Service</h5> <div class="endpoint post indent">/services/{service name or id}/plugins</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Service that should be associated to the newly-created Plugin.</td> </tr> </tbody> </table> <h5 id="create-plugin-associated-to-a-specific-consumer">Create Plugin Associated to a Specific Consumer</h5> <div class="endpoint post indent">/consumers/{consumer name or id}/plugins</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Consumer that should be associated to the newly-created Plugin.</td> </tr> </tbody> </table> <h4 id="request-body-9">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">route.id=<route id></code> or <code class="language-plaintext highlighter-rouge">route.name=<route name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"route":{"id":"<route id>"}</code> or <code class="language-plaintext highlighter-rouge">"route":{"name":"<route name>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">service.id=<service id></code> or <code class="language-plaintext highlighter-rouge">service.name=<service name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"service":{"id":"<service id>"}</code> or <code class="language-plaintext highlighter-rouge">"service":{"name":"<service name>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">consumer.id=<consumer id></code> or <code class="language-plaintext highlighter-rouge">consumer.username=<consumer username></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"consumer":{"id":"<consumer id>"}</code> or <code class="language-plaintext highlighter-rouge">"consumer":{"username":"<consumer username>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> optional </td> <td>The configuration properties for the Plugin which can be found on the plugins documentation page in the <a href="/hub/">Kong Hub</a>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocols</code></td> <td>A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support <code class="language-plaintext highlighter-rouge">"tcp"</code> and <code class="language-plaintext highlighter-rouge">"tls"</code>. Default: <code class="language-plaintext highlighter-rouge">["grpc", "grpcs", "http",</code><code class="language-plaintext highlighter-rouge"> "https"]</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">enabled</code></td> <td>Whether the plugin is applied. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Plugin for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-30">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7", "name": "rate-limiting", "created_at": 1422386534, "route": null, "service": null, "consumer": null, "config": {"minute":20, "hour":500}, "protocols": ["http", "https"], "enabled": true, "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-plugins">List Plugins</h3> <h5 id="list-all-plugins">List All Plugins</h5> <div class="endpoint get indent">/plugins</div> <h5 id="list-plugins-associated-to-a-specific-route">List Plugins Associated to a Specific Route</h5> <div class="endpoint get indent">/routes/{route name or id}/plugins</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Route whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Route will be listed.</td> </tr> </tbody> </table> <h5 id="list-plugins-associated-to-a-specific-service">List Plugins Associated to a Specific Service</h5> <div class="endpoint get indent">/services/{service name or id}/plugins</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Service whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Service will be listed.</td> </tr> </tbody> </table> <h5 id="list-plugins-associated-to-a-specific-consumer">List Plugins Associated to a Specific Consumer</h5> <div class="endpoint get indent">/consumers/{consumer name or id}/plugins</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Consumer whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Consumer will be listed.</td> </tr> </tbody> </table> <h4 id="response-31">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "02621eee-8309-4bf6-b36b-a82017a5393e", "name": "rate-limiting", "created_at": 1422386534, "route": null, "service": null, "consumer": null, "config": {"minute":20, "hour":500}, "protocols": ["http", "https"], "enabled": true, "tags": ["user-level", "low-priority"] }, { "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4", "name": "rate-limiting", "created_at": 1422386534, "route": null, "service": null, "consumer": null, "config": {"minute":20, "hour":500}, "protocols": ["tcp", "tls"], "enabled": true, "tags": ["admin", "high-priority", "critical"] }], "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-plugin">Retrieve Plugin</h3> <h5 id="retrieve-plugin-1">Retrieve Plugin</h5> <div class="endpoint get indent">/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-plugin-associated-to-a-specific-route">Retrieve Plugin Associated to a Specific Route</h5> <div class="endpoint get indent">/routes/{route name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-plugin-associated-to-a-specific-service">Retrieve Plugin Associated to a Specific Service</h5> <div class="endpoint get indent">/services/{service name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-plugin-associated-to-a-specific-consumer">Retrieve Plugin Associated to a Specific Consumer</h5> <div class="endpoint get indent">/consumers/{consumer username or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to retrieve.</td> </tr> </tbody> </table> <h4 id="response-32">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7", "name": "rate-limiting", "created_at": 1422386534, "route": null, "service": null, "consumer": null, "config": {"minute":20, "hour":500}, "protocols": ["http", "https"], "enabled": true, "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-plugin">Update Plugin</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-plugin-1">Update Plugin</h5> <div class="endpoint patch indent">/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to update.</td> </tr> </tbody> </table> <h5 id="update-plugin-associated-to-a-specific-route">Update Plugin Associated to a Specific Route</h5> <div class="endpoint patch indent">/routes/{route name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to update.</td> </tr> </tbody> </table> <h5 id="update-plugin-associated-to-a-specific-service">Update Plugin Associated to a Specific Service</h5> <div class="endpoint patch indent">/services/{service name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to update.</td> </tr> </tbody> </table> <h5 id="update-plugin-associated-to-a-specific-consumer">Update Plugin Associated to a Specific Consumer</h5> <div class="endpoint patch indent">/consumers/{consumer username or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to update.</td> </tr> </tbody> </table> <h4 id="request-body-10">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">route.id=<route id></code> or <code class="language-plaintext highlighter-rouge">route.name=<route name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"route":{"id":"<route id>"}</code> or <code class="language-plaintext highlighter-rouge">"route":{"name":"<route name>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">service.id=<service id></code> or <code class="language-plaintext highlighter-rouge">service.name=<service name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"service":{"id":"<service id>"}</code> or <code class="language-plaintext highlighter-rouge">"service":{"name":"<service name>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">consumer.id=<consumer id></code> or <code class="language-plaintext highlighter-rouge">consumer.username=<consumer username></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"consumer":{"id":"<consumer id>"}</code> or <code class="language-plaintext highlighter-rouge">"consumer":{"username":"<consumer username>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> optional </td> <td>The configuration properties for the Plugin which can be found on the plugins documentation page in the <a href="/hub/">Kong Hub</a>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocols</code></td> <td>A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support <code class="language-plaintext highlighter-rouge">"tcp"</code> and <code class="language-plaintext highlighter-rouge">"tls"</code>. Default: <code class="language-plaintext highlighter-rouge">["grpc", "grpcs", "http",</code><code class="language-plaintext highlighter-rouge"> "https"]</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">enabled</code></td> <td>Whether the plugin is applied. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Plugin for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-33">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7", "name": "rate-limiting", "created_at": 1422386534, "route": null, "service": null, "consumer": null, "config": {"minute":20, "hour":500}, "protocols": ["http", "https"], "enabled": true, "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-or-create-plugin">Update Or Create Plugin</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-plugin">Create Or Update Plugin</h5> <div class="endpoint put indent">/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-plugin-associated-to-a-specific-route">Create Or Update Plugin Associated to a Specific Route</h5> <div class="endpoint put indent">/routes/{route name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-plugin-associated-to-a-specific-service">Create Or Update Plugin Associated to a Specific Service</h5> <div class="endpoint put indent">/services/{service name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-plugin-associated-to-a-specific-consumer">Create Or Update Plugin Associated to a Specific Consumer</h5> <div class="endpoint put indent">/consumers/{consumer username or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to create or update.</td> </tr> </tbody> </table> <h4 id="request-body-11">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">route.id=<route id></code> or <code class="language-plaintext highlighter-rouge">route.name=<route name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"route":{"id":"<route id>"}</code> or <code class="language-plaintext highlighter-rouge">"route":{"name":"<route name>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">service.id=<service id></code> or <code class="language-plaintext highlighter-rouge">service.name=<service name></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"service":{"id":"<service id>"}</code> or <code class="language-plaintext highlighter-rouge">"service":{"name":"<service name>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">null</code>.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">consumer.id=<consumer id></code> or <code class="language-plaintext highlighter-rouge">consumer.username=<consumer username></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"consumer":{"id":"<consumer id>"}</code> or <code class="language-plaintext highlighter-rouge">"consumer":{"username":"<consumer username>"}</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> optional </td> <td>The configuration properties for the Plugin which can be found on the plugins documentation page in the <a href="/hub/">Kong Hub</a>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">protocols</code></td> <td>A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support <code class="language-plaintext highlighter-rouge">"tcp"</code> and <code class="language-plaintext highlighter-rouge">"tls"</code>. Default: <code class="language-plaintext highlighter-rouge">["grpc", "grpcs", "http",</code><code class="language-plaintext highlighter-rouge"> "https"]</code>.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">enabled</code></td> <td>Whether the plugin is applied. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Plugin for grouping and filtering.</td> </tr> </tbody> </table> Inserts (or replaces) the Plugin under the requested resource with the definition specified in the body. The Plugin will be identified via the <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the Plugin being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new Plugin without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-34">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-plugin">Delete Plugin</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-plugin-1">Delete Plugin</h5> <div class="endpoint delete indent">/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to delete.</td> </tr> </tbody> </table> <h5 id="delete-plugin-associated-to-a-specific-route">Delete Plugin Associated to a Specific Route</h5> <div class="endpoint delete indent">/routes/{route name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">route name or id</code> required </td> <td>The unique identifier or the name of the Route to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to delete.</td> </tr> </tbody> </table> <h5 id="delete-plugin-associated-to-a-specific-service">Delete Plugin Associated to a Specific Service</h5> <div class="endpoint delete indent">/services/{service name or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">service name or id</code> required </td> <td>The unique identifier or the name of the Service to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to delete.</td> </tr> </tbody> </table> <h5 id="delete-plugin-associated-to-a-specific-consumer">Delete Plugin Associated to a Specific Consumer</h5> <div class="endpoint delete indent">/consumers/{consumer username or id}/plugins/{plugin id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">consumer username or id</code> required </td> <td>The unique identifier or the username of the Consumer to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">plugin id</code> required </td> <td>The unique identifier of the Plugin to delete.</td> </tr> </tbody> </table> <h4 id="response-35">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-enabled-plugins">Retrieve Enabled Plugins</h3> Retrieve a list of all installed plugins on the Kong node. <div class="endpoint get">/plugins/enabled</div> <h4 id="response-36">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "enabled_plugins": [ "jwt", "acl", "cors", "oauth2", "tcp-log", "udp-log", "file-log", "http-log", "key-auth", "hmac-auth", "basic-auth", "ip-restriction", "request-transformer", "response-transformer", "request-size-limiting", "rate-limiting", "response-ratelimiting", "aws-lambda", "bot-detection", "correlation-id", "datadog", "galileo", "ldap-auth", "loggly", "statsd", "syslog" ] } </code></pre></div></div> <hr> <h2 id="certificate-object">Certificate Object</h2> 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 <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "key": "-----BEGIN RSA PRIVATE KEY-----...", "cert_alt": "-----BEGIN CERTIFICATE-----...", "key_alt": "-----BEGIN EC PRIVATE KEY-----...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <h3 id="add-certificate">Add Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-certificate">Create Certificate</h5> <div class="endpoint post indent">/certificates</div> <h4 id="request-body-12">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">cert</code></td> <td>PEM-encoded public certificate chain of the SSL key pair.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">key</code></td> <td>PEM-encoded private key of the SSL key pair.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">cert_alt</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">key_alt</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Certificate for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">snis</code> shorthand-attribute </td> <td>An array of zero or more hostnames to associate with this certificate as SNIs. This is a convenience parameter: under the hood, it creates an SNI object and associates it with this certificate. To set this attribute this certificate must have a valid private key associated with it.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">passphrase</code> optional (Enterprise only)</td> <td>To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong’s database, consider using DB encryption.</td> </tr> </tbody> </table> <h4 id="response-37">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "key": "-----BEGIN RSA PRIVATE KEY-----...", "cert_alt": "-----BEGIN CERTIFICATE-----...", "key_alt": "-----BEGIN EC PRIVATE KEY-----...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-certificates">List Certificates</h3> <h5 id="list-all-certificates">List All Certificates</h5> <div class="endpoint get indent">/certificates</div> <h4 id="response-38">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "key": "-----BEGIN RSA PRIVATE KEY-----...", "cert_alt": "-----BEGIN CERTIFICATE-----...", "key_alt": "-----BEGIN EC PRIVATE KEY-----...", "tags": ["user-level", "low-priority"] }, { "id": "a9b2107f-a214-47b3-add4-46b942187924", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "key": "-----BEGIN RSA PRIVATE KEY-----...", "cert_alt": "-----BEGIN CERTIFICATE-----...", "key_alt": "-----BEGIN EC PRIVATE KEY-----...", "tags": ["admin", "high-priority", "critical"] }], "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-certificate">Retrieve Certificate</h3> <h5 id="retrieve-certificate-1">Retrieve Certificate</h5> <div class="endpoint get indent">/certificates/{certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-certificate-associated-to-a-specific-upstream">Retrieve Certificate Associated to a Specific Upstream</h5> <div class="endpoint get indent">/upstreams/{upstream name or id}/client_certificate</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream associated to the Certificate to be retrieved.</td> </tr> </tbody> </table> <h4 id="response-39">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "key": "-----BEGIN RSA PRIVATE KEY-----...", "cert_alt": "-----BEGIN CERTIFICATE-----...", "key_alt": "-----BEGIN EC PRIVATE KEY-----...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-certificate">Update Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-certificate-1">Update Certificate</h5> <div class="endpoint patch indent">/certificates/{certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to update.</td> </tr> </tbody> </table> <h5 id="update-certificate-associated-to-a-specific-upstream">Update Certificate Associated to a Specific Upstream</h5> <div class="endpoint patch indent">/upstreams/{upstream name or id}/client_certificate</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream associated to the Certificate to be updated.</td> </tr> </tbody> </table> <h4 id="request-body-13">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">cert</code></td> <td>PEM-encoded public certificate chain of the SSL key pair.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">key</code></td> <td>PEM-encoded private key of the SSL key pair.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">cert_alt</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">key_alt</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Certificate for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">snis</code> shorthand-attribute </td> <td>An array of zero or more hostnames to associate with this certificate as SNIs. This is a convenience parameter: under the hood, it creates an SNI object and associates it with this certificate. To set this attribute this certificate must have a valid private key associated with it.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">passphrase</code> optional (Enterprise only)</td> <td>To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong’s database, consider using DB encryption.</td> </tr> </tbody> </table> <h4 id="response-40">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "key": "-----BEGIN RSA PRIVATE KEY-----...", "cert_alt": "-----BEGIN CERTIFICATE-----...", "key_alt": "-----BEGIN EC PRIVATE KEY-----...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-or-create-certificate">Update Or Create Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-certificate">Create Or Update Certificate</h5> <div class="endpoint put indent">/certificates/{certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-certificate-associated-to-a-specific-upstream">Create Or Update Certificate Associated to a Specific Upstream</h5> <div class="endpoint put indent">/upstreams/{upstream name or id}/client_certificate</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream associated to the Certificate to be created or updated.</td> </tr> </tbody> </table> <h4 id="request-body-14">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">cert</code></td> <td>PEM-encoded public certificate chain of the SSL key pair.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">key</code></td> <td>PEM-encoded private key of the SSL key pair.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">cert_alt</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">key_alt</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Certificate for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">snis</code> shorthand-attribute </td> <td>An array of zero or more hostnames to associate with this certificate as SNIs. This is a convenience parameter: under the hood, it creates an SNI object and associates it with this certificate. To set this attribute this certificate must have a valid private key associated with it.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">passphrase</code> optional (Enterprise only)</td> <td>To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong’s database, consider using DB encryption.</td> </tr> </tbody> </table> Inserts (or replaces) the Certificate under the requested resource with the definition specified in the body. The Certificate will be identified via the <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the Certificate being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new Certificate without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-41">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-certificate">Delete Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-certificate-1">Delete Certificate</h5> <div class="endpoint delete indent">/certificates/{certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to delete.</td> </tr> </tbody> </table> <h5 id="delete-certificate-associated-to-a-specific-upstream">Delete Certificate Associated to a Specific Upstream</h5> <div class="endpoint delete indent">/upstreams/{upstream name or id}/client_certificate</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream associated to the Certificate to be deleted.</td> </tr> </tbody> </table> <h4 id="response-42">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h2 id="ca-certificate-object">CA Certificate Object</h2> 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 <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <h3 id="add-ca-certificate">Add CA Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-ca-certificate">Create CA Certificate</h5> <div class="endpoint post indent">/ca_certificates</div> <h4 id="request-body-15">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">cert</code></td> <td>PEM-encoded public certificate of the CA.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">cert_digest</code> optional </td> <td>SHA256 hex digest of the public certificate.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Certificate for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-43">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-ca-certificates">List CA Certificates</h3> <h5 id="list-all-ca-certificates">List All CA Certificates</h5> <div class="endpoint get indent">/ca_certificates</div> <h4 id="response-44">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "43429efd-b3a5-4048-94cb-5cc4029909bb", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", "tags": ["user-level", "low-priority"] }, { "id": "d26761d5-83a4-4f24-ac6c-cff276f2b79c", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", "tags": ["admin", "high-priority", "critical"] }], "next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-ca-certificate">Retrieve CA Certificate</h3> <h5 id="retrieve-ca-certificate-1">Retrieve CA Certificate</h5> <div class="endpoint get indent">/ca_certificates/{ca_certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificate id</code> required </td> <td>The unique identifier of the CA Certificate to retrieve.</td> </tr> </tbody> </table> <h4 id="response-45">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-ca-certificate">Update CA Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-ca-certificate-1">Update CA Certificate</h5> <div class="endpoint patch indent">/ca_certificates/{ca_certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificate id</code> required </td> <td>The unique identifier of the CA Certificate to update.</td> </tr> </tbody> </table> <h4 id="request-body-16">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">cert</code></td> <td>PEM-encoded public certificate of the CA.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">cert_digest</code> optional </td> <td>SHA256 hex digest of the public certificate.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Certificate for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-46">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f", "created_at": 1422386534, "cert": "-----BEGIN CERTIFICATE-----...", "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 id="update-or-create-ca-certificate">Update Or Create CA Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-ca-certificate">Create Or Update CA Certificate</h5> <div class="endpoint put indent">/ca_certificates/{ca_certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificate id</code> required </td> <td>The unique identifier of the CA Certificate to create or update.</td> </tr> </tbody> </table> <h4 id="request-body-17">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">cert</code></td> <td>PEM-encoded public certificate of the CA.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">cert_digest</code> optional </td> <td>SHA256 hex digest of the public certificate.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Certificate for grouping and filtering.</td> </tr> </tbody> </table> 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 <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the CA Certificate being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new CA Certificate without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-47">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-ca-certificate">Delete CA Certificate</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-ca-certificate-1">Delete CA Certificate</h5> <div class="endpoint delete indent">/ca_certificates/{ca_certificate id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">ca_certificate id</code> required </td> <td>The unique identifier of the CA Certificate to delete.</td> </tr> </tbody> </table> <h4 id="response-48">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h2 id="sni-object">SNI Object</h2> 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 <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "91020192-062d-416f-a275-9addeeaffaf2", "name": "my-sni", "created_at": 1422386534, "tags": ["user-level", "low-priority"], "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"} } </code></pre></div></div> <h3 id="add-sni">Add SNI</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-sni">Create SNI</h5> <div class="endpoint post indent">/snis</div> <h5 id="create-sni-associated-to-a-specific-certificate">Create SNI Associated to a Specific Certificate</h5> <div class="endpoint post indent">/certificates/{certificate name or id}/snis</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Certificate that should be associated to the newly-created SNI.</td> </tr> </tbody> </table> <h4 id="request-body-18">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The SNI name to associate with the given certificate.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the SNIs for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">certificate</code></td> <td>The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">certificate.id=<certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"certificate":{"id":"<certificate id>"}</code>.</td> </tr> </tbody> </table> <h4 id="response-49">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "91020192-062d-416f-a275-9addeeaffaf2", "name": "my-sni", "created_at": 1422386534, "tags": ["user-level", "low-priority"], "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"} } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-snis">List SNIs</h3> <h5 id="list-all-snis">List All SNIs</h5> <div class="endpoint get indent">/snis</div> <h5 id="list-snis-associated-to-a-specific-certificate">List SNIs Associated to a Specific Certificate</h5> <div class="endpoint get indent">/certificates/{certificate name or id}/snis</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed.</td> </tr> </tbody> </table> <h4 id="response-50">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "147f5ef0-1ed6-4711-b77f-489262f8bff7", "name": "my-sni", "created_at": 1422386534, "tags": ["user-level", "low-priority"], "certificate": {"id":"a3ad71a8-6685-4b03-a101-980a953544f6"} }, { "id": "b87eb55d-69a1-41d2-8653-8d706eecefc0", "name": "my-sni", "created_at": 1422386534, "tags": ["admin", "high-priority", "critical"], "certificate": {"id":"4e8d95d4-40f2-4818-adcb-30e00c349618"} }], "next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-sni">Retrieve SNI</h3> <h5 id="retrieve-sni-1">Retrieve SNI</h5> <div class="endpoint get indent">/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-sni-associated-to-a-specific-certificate">Retrieve SNI Associated to a Specific Certificate</h5> <div class="endpoint get indent">/certificates/{certificate id}/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to retrieve.</td> </tr> </tbody> </table> <h4 id="response-51">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "91020192-062d-416f-a275-9addeeaffaf2", "name": "my-sni", "created_at": 1422386534, "tags": ["user-level", "low-priority"], "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"} } </code></pre></div></div> <hr> <h3 id="update-sni">Update SNI</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-sni-1">Update SNI</h5> <div class="endpoint patch indent">/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to update.</td> </tr> </tbody> </table> <h5 id="update-sni-associated-to-a-specific-certificate">Update SNI Associated to a Specific Certificate</h5> <div class="endpoint patch indent">/certificates/{certificate id}/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to update.</td> </tr> </tbody> </table> <h4 id="request-body-19">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The SNI name to associate with the given certificate.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the SNIs for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">certificate</code></td> <td>The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">certificate.id=<certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"certificate":{"id":"<certificate id>"}</code>.</td> </tr> </tbody> </table> <h4 id="response-52">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "91020192-062d-416f-a275-9addeeaffaf2", "name": "my-sni", "created_at": 1422386534, "tags": ["user-level", "low-priority"], "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"} } </code></pre></div></div> <hr> <h3 id="update-or-create-sni">Update Or Create SNI</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-sni">Create Or Update SNI</h5> <div class="endpoint put indent">/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-sni-associated-to-a-specific-certificate">Create Or Update SNI Associated to a Specific Certificate</h5> <div class="endpoint put indent">/certificates/{certificate id}/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to create or update.</td> </tr> </tbody> </table> <h4 id="request-body-20">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The SNI name to associate with the given certificate.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the SNIs for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">certificate</code></td> <td>The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">certificate.id=<certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"certificate":{"id":"<certificate id>"}</code>.</td> </tr> </tbody> </table> Inserts (or replaces) the SNI under the requested resource with the definition specified in the body. The SNI will be identified via the <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the SNI being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new SNI without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-53">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-sni">Delete SNI</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-sni-1">Delete SNI</h5> <div class="endpoint delete indent">/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to delete.</td> </tr> </tbody> </table> <h5 id="delete-sni-associated-to-a-specific-certificate">Delete SNI Associated to a Specific Certificate</h5> <div class="endpoint delete indent">/certificates/{certificate id}/snis/{sni name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">sni name or id</code> required </td> <td>The unique identifier or the name of the SNI to delete.</td> </tr> </tbody> </table> <h4 id="response-54">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h2 id="upstream-object">Upstream Object</h2> 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 <code class="language-plaintext highlighter-rouge">service.v1.xyz</code> for a Service object whose <code class="language-plaintext highlighter-rouge">host</code> is <code class="language-plaintext highlighter-rouge">service.v1.xyz</code>. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a <a href="/gateway/2.8.x/reference/health-checks-circuit-breakers">health checker</a>, 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 <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70", "created_at": 1422386534, "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "active": { "timeout": 1, "unhealthy": { "interval": 0, "tcp_failures": 0, "timeouts": 0, "http_failures": 0, "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505] }, "type": "http", "concurrency": 10, "headers": [{"x-another-header":["bla"], "x-my-header":["foo", "bar"]}], "healthy": { "interval": 0, "successes": 0, "http_statuses": [200, 302] }, "http_path": "/", "https_sni": "example.com", "https_verify_certificate": true }, "passive": { "type": "http", "unhealthy": { "http_statuses": [429, 500, 503], "http_failures": 0, "timeouts": 0, "tcp_failures": 0 }, "healthy": { "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308], "successes": 0 } }, "threshold": 0 }, "tags": ["user-level", "low-priority"], "host_header": "example.com", "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"} } </code></pre></div></div> <h3 id="add-upstream">Add Upstream</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-upstream">Create Upstream</h5> <div class="endpoint post indent">/upstreams</div> <h5 id="create-upstream-associated-to-a-specific-certificate">Create Upstream Associated to a Specific Certificate</h5> <div class="endpoint post indent">/certificates/{certificate name or id}/upstreams</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Certificate that should be associated to the newly-created Upstream.</td> </tr> </tbody> </table> <h4 id="request-body-21">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>This is a hostname, which must be equal to the <code class="language-plaintext highlighter-rouge">host</code> of a Service.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">algorithm</code> optional </td> <td>Which load balancing algorithm to use. Accepted values are: <code class="language-plaintext highlighter-rouge">"consistent-hashing"</code>, <code class="language-plaintext highlighter-rouge">"least-connections"</code>, <code class="language-plaintext highlighter-rouge">"round-robin"</code>. Default: <code class="language-plaintext highlighter-rouge">"round-robin"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on</code> optional </td> <td>What to use as hashing input. Using <code class="language-plaintext highlighter-rouge">none</code> results in a weighted-round-robin scheme with no hashing. Accepted values are: <code class="language-plaintext highlighter-rouge">"none"</code>, <code class="language-plaintext highlighter-rouge">"consumer"</code>, <code class="language-plaintext highlighter-rouge">"ip"</code>, <code class="language-plaintext highlighter-rouge">"header"</code>, <code class="language-plaintext highlighter-rouge">"cookie"</code>. Default: <code class="language-plaintext highlighter-rouge">"none"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_fallback</code> optional </td> <td>What to use as hashing input if the primary <code class="language-plaintext highlighter-rouge">hash_on</code> does not return a hash (for example, header is missing, or no Consumer identified). Not available if <code class="language-plaintext highlighter-rouge">hash_on</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. Accepted values are: <code class="language-plaintext highlighter-rouge">"none"</code>, <code class="language-plaintext highlighter-rouge">"consumer"</code>, <code class="language-plaintext highlighter-rouge">"ip"</code>, <code class="language-plaintext highlighter-rouge">"header"</code>, <code class="language-plaintext highlighter-rouge">"cookie"</code>. Default: <code class="language-plaintext highlighter-rouge">"none"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_header</code> semi-optional </td> <td>The header name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> is set to <code class="language-plaintext highlighter-rouge">header</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_fallback_header</code> semi-optional </td> <td>The header name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">header</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_cookie</code> semi-optional </td> <td>The cookie name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> or <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_cookie_path</code> semi-optional </td> <td>The cookie path to set in the response headers. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> or <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. Default: <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">slots</code> optional </td> <td>The number of slots in the load balancer algorithm. If <code class="language-plaintext highlighter-rouge">algorithm</code> is set to <code class="language-plaintext highlighter-rouge">round-robin</code>, this setting determines the maximum number of slots. If <code class="language-plaintext highlighter-rouge">algorithm</code> is set to <code class="language-plaintext highlighter-rouge">consistent-hashing</code>, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range <code class="language-plaintext highlighter-rouge">10</code>-<code class="language-plaintext highlighter-rouge">65536</code>. Default: <code class="language-plaintext highlighter-rouge">10000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">timeout</code> optional </td> <td>Socket timeout for active health checks (in seconds). Default: <code class="language-plaintext highlighter-rouge">1</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.interval</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.tcp_failures</code> optional </td> <td>Number of TCP failures in active probes to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.timeouts</code> optional </td> <td>Number of timeouts in active probes to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_failures</code> optional </td> <td>Number of HTTP failures in active probes (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.active.unhealthy.http_statuses</code>) to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_statuses</code> optional </td> <td>An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: <code class="language-plaintext highlighter-rouge">[429, 404, 500, 501, 502, 503,</code><code class="language-plaintext highlighter-rouge"> 504, 505]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=429&http_statuses[]=404</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.type</code> optional </td> <td>Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">concurrency</code> optional </td> <td>Number of targets to check concurrently in active health checks. Default: <code class="language-plaintext highlighter-rouge">10</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">headers</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.interval</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.successes</code> optional </td> <td>Number of successes in active probes (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.active.healthy.http_statuses</code>) to consider a target healthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.http_statuses</code> optional </td> <td>An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: <code class="language-plaintext highlighter-rouge">[200, 302]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=200&http_statuses[]=302</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">http_path</code> optional </td> <td>Path to use in GET HTTP request to run as a probe on active health checks. Default: <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">https_sni</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">https_verify_certificate</code> </td> <td>Whether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">type</code> optional </td> <td>Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, <code class="language-plaintext highlighter-rouge">http</code> and <code class="language-plaintext highlighter-rouge">https</code> options are equivalent. Accepted values are: <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_statuses</code> optional </td> <td>An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">[429, 500, 503]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=429&http_statuses[]=500</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_failures</code> optional </td> <td>Number of HTTP failures in proxied traffic (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.passive.unhealthy.http_statuses</code>) to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.timeouts</code> optional </td> <td>Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.tcp_failures</code> optional </td> <td>Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">healthy.http_statuses</code> optional </td> <td>An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">[200, 201, 202, 203, 204, 205,</code><code class="language-plaintext highlighter-rouge"> 206, 207, 208, 226, 300, 301,</code><code class="language-plaintext highlighter-rouge"> 302, 303, 304, 305, 306, 307,</code><code class="language-plaintext highlighter-rouge"> 308]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=200&http_statuses[]=201</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">healthy.successes</code> optional </td> <td>Number of successes in proxied traffic (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.passive.healthy.http_statuses</code>) to consider a target healthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.threshold</code> optional </td> <td>The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Upstream for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">host_header</code> optional </td> <td>The hostname to be used as <code class="language-plaintext highlighter-rouge">Host</code> header when proxying requests through Kong.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">client_certificate</code> optional </td> <td>If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">client_certificate.id=<client_certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"client_certificate":{"id":"<client_certificate id>"}</code>.</td> </tr> </tbody> </table> <h4 id="response-55">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70", "created_at": 1422386534, "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "active": { "timeout": 1, "unhealthy": { "interval": 0, "tcp_failures": 0, "timeouts": 0, "http_failures": 0, "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505] }, "type": "http", "concurrency": 10, "headers": [{"x-another-header":["bla"], "x-my-header":["foo", "bar"]}], "healthy": { "interval": 0, "successes": 0, "http_statuses": [200, 302] }, "http_path": "/", "https_sni": "example.com", "https_verify_certificate": true }, "passive": { "type": "http", "unhealthy": { "http_statuses": [429, 500, 503], "http_failures": 0, "timeouts": 0, "tcp_failures": 0 }, "healthy": { "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308], "successes": 0 } }, "threshold": 0 }, "tags": ["user-level", "low-priority"], "host_header": "example.com", "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"} } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-upstreams">List Upstreams</h3> <h5 id="list-all-upstreams">List All Upstreams</h5> <div class="endpoint get indent">/upstreams</div> <h5 id="list-upstreams-associated-to-a-specific-certificate">List Upstreams Associated to a Specific Certificate</h5> <div class="endpoint get indent">/certificates/{certificate name or id}/upstreams</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate name or id</code> required </td> <td>The unique identifier or the <code class="language-plaintext highlighter-rouge">name</code> attribute of the Certificate whose Upstreams are to be retrieved. When using this endpoint, only Upstreams associated to the specified Certificate will be listed.</td> </tr> </tbody> </table> <h4 id="response-56">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "4fe14415-73d5-4f00-9fbc-c72a0fccfcb2", "created_at": 1422386534, "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "active": { "timeout": 1, "unhealthy": { "interval": 0, "tcp_failures": 0, "timeouts": 0, "http_failures": 0, "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505] }, "type": "http", "concurrency": 10, "headers": [{"x-another-header":["bla"], "x-my-header":["foo", "bar"]}], "healthy": { "interval": 0, "successes": 0, "http_statuses": [200, 302] }, "http_path": "/", "https_sni": "example.com", "https_verify_certificate": true }, "passive": { "type": "http", "unhealthy": { "http_statuses": [429, 500, 503], "http_failures": 0, "timeouts": 0, "tcp_failures": 0 }, "healthy": { "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308], "successes": 0 } }, "threshold": 0 }, "tags": ["user-level", "low-priority"], "host_header": "example.com", "client_certificate": {"id":"a3395f66-2af6-4c79-bea2-1b6933764f80"} }, { "id": "885a0392-ef1b-4de3-aacf-af3f1697ce2c", "created_at": 1422386534, "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "active": { "timeout": 1, "unhealthy": { "interval": 0, "tcp_failures": 0, "timeouts": 0, "http_failures": 0, "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505] }, "type": "http", "concurrency": 10, "headers": [{"x-another-header":["bla"], "x-my-header":["foo", "bar"]}], "healthy": { "interval": 0, "successes": 0, "http_statuses": [200, 302] }, "http_path": "/", "https_sni": "example.com", "https_verify_certificate": true }, "passive": { "type": "http", "unhealthy": { "http_statuses": [429, 500, 503], "http_failures": 0, "timeouts": 0, "tcp_failures": 0 }, "healthy": { "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308], "successes": 0 } }, "threshold": 0 }, "tags": ["admin", "high-priority", "critical"], "host_header": "example.com", "client_certificate": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"} }], "next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-upstream">Retrieve Upstream</h3> <h5 id="retrieve-upstream-1">Retrieve Upstream</h5> <div class="endpoint get indent">/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to retrieve.</td> </tr> </tbody> </table> <h5 id="retrieve-upstream-associated-to-a-specific-certificate">Retrieve Upstream Associated to a Specific Certificate</h5> <div class="endpoint get indent">/certificates/{certificate id}/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to retrieve.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to retrieve.</td> </tr> </tbody> </table> <h4 id="response-57">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70", "created_at": 1422386534, "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "active": { "timeout": 1, "unhealthy": { "interval": 0, "tcp_failures": 0, "timeouts": 0, "http_failures": 0, "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505] }, "type": "http", "concurrency": 10, "headers": [{"x-another-header":["bla"], "x-my-header":["foo", "bar"]}], "healthy": { "interval": 0, "successes": 0, "http_statuses": [200, 302] }, "http_path": "/", "https_sni": "example.com", "https_verify_certificate": true }, "passive": { "type": "http", "unhealthy": { "http_statuses": [429, 500, 503], "http_failures": 0, "timeouts": 0, "tcp_failures": 0 }, "healthy": { "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308], "successes": 0 } }, "threshold": 0 }, "tags": ["user-level", "low-priority"], "host_header": "example.com", "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"} } </code></pre></div></div> <hr> <h3 id="update-upstream">Update Upstream</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-upstream-1">Update Upstream</h5> <div class="endpoint patch indent">/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to update.</td> </tr> </tbody> </table> <h5 id="update-upstream-associated-to-a-specific-certificate">Update Upstream Associated to a Specific Certificate</h5> <div class="endpoint patch indent">/certificates/{certificate id}/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to update.</td> </tr> </tbody> </table> <h4 id="request-body-22">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>This is a hostname, which must be equal to the <code class="language-plaintext highlighter-rouge">host</code> of a Service.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">algorithm</code> optional </td> <td>Which load balancing algorithm to use. Accepted values are: <code class="language-plaintext highlighter-rouge">"consistent-hashing"</code>, <code class="language-plaintext highlighter-rouge">"least-connections"</code>, <code class="language-plaintext highlighter-rouge">"round-robin"</code>. Default: <code class="language-plaintext highlighter-rouge">"round-robin"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on</code> optional </td> <td>What to use as hashing input. Using <code class="language-plaintext highlighter-rouge">none</code> results in a weighted-round-robin scheme with no hashing. Accepted values are: <code class="language-plaintext highlighter-rouge">"none"</code>, <code class="language-plaintext highlighter-rouge">"consumer"</code>, <code class="language-plaintext highlighter-rouge">"ip"</code>, <code class="language-plaintext highlighter-rouge">"header"</code>, <code class="language-plaintext highlighter-rouge">"cookie"</code>. Default: <code class="language-plaintext highlighter-rouge">"none"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_fallback</code> optional </td> <td>What to use as hashing input if the primary <code class="language-plaintext highlighter-rouge">hash_on</code> does not return a hash (for example, header is missing, or no Consumer identified). Not available if <code class="language-plaintext highlighter-rouge">hash_on</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. Accepted values are: <code class="language-plaintext highlighter-rouge">"none"</code>, <code class="language-plaintext highlighter-rouge">"consumer"</code>, <code class="language-plaintext highlighter-rouge">"ip"</code>, <code class="language-plaintext highlighter-rouge">"header"</code>, <code class="language-plaintext highlighter-rouge">"cookie"</code>. Default: <code class="language-plaintext highlighter-rouge">"none"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_header</code> semi-optional </td> <td>The header name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> is set to <code class="language-plaintext highlighter-rouge">header</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_fallback_header</code> semi-optional </td> <td>The header name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">header</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_cookie</code> semi-optional </td> <td>The cookie name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> or <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_cookie_path</code> semi-optional </td> <td>The cookie path to set in the response headers. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> or <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. Default: <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">slots</code> optional </td> <td>The number of slots in the load balancer algorithm. If <code class="language-plaintext highlighter-rouge">algorithm</code> is set to <code class="language-plaintext highlighter-rouge">round-robin</code>, this setting determines the maximum number of slots. If <code class="language-plaintext highlighter-rouge">algorithm</code> is set to <code class="language-plaintext highlighter-rouge">consistent-hashing</code>, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range <code class="language-plaintext highlighter-rouge">10</code>-<code class="language-plaintext highlighter-rouge">65536</code>. Default: <code class="language-plaintext highlighter-rouge">10000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">timeout</code> optional </td> <td>Socket timeout for active health checks (in seconds). Default: <code class="language-plaintext highlighter-rouge">1</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.interval</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.tcp_failures</code> optional </td> <td>Number of TCP failures in active probes to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.timeouts</code> optional </td> <td>Number of timeouts in active probes to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_failures</code> optional </td> <td>Number of HTTP failures in active probes (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.active.unhealthy.http_statuses</code>) to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_statuses</code> optional </td> <td>An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: <code class="language-plaintext highlighter-rouge">[429, 404, 500, 501, 502, 503,</code><code class="language-plaintext highlighter-rouge"> 504, 505]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=429&http_statuses[]=404</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.type</code> optional </td> <td>Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">concurrency</code> optional </td> <td>Number of targets to check concurrently in active health checks. Default: <code class="language-plaintext highlighter-rouge">10</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">headers</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.interval</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.successes</code> optional </td> <td>Number of successes in active probes (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.active.healthy.http_statuses</code>) to consider a target healthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.http_statuses</code> optional </td> <td>An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: <code class="language-plaintext highlighter-rouge">[200, 302]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=200&http_statuses[]=302</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">http_path</code> optional </td> <td>Path to use in GET HTTP request to run as a probe on active health checks. Default: <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">https_sni</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">https_verify_certificate</code> </td> <td>Whether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">type</code> optional </td> <td>Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, <code class="language-plaintext highlighter-rouge">http</code> and <code class="language-plaintext highlighter-rouge">https</code> options are equivalent. Accepted values are: <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_statuses</code> optional </td> <td>An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">[429, 500, 503]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=429&http_statuses[]=500</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_failures</code> optional </td> <td>Number of HTTP failures in proxied traffic (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.passive.unhealthy.http_statuses</code>) to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.timeouts</code> optional </td> <td>Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.tcp_failures</code> optional </td> <td>Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">healthy.http_statuses</code> optional </td> <td>An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">[200, 201, 202, 203, 204, 205,</code><code class="language-plaintext highlighter-rouge"> 206, 207, 208, 226, 300, 301,</code><code class="language-plaintext highlighter-rouge"> 302, 303, 304, 305, 306, 307,</code><code class="language-plaintext highlighter-rouge"> 308]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=200&http_statuses[]=201</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">healthy.successes</code> optional </td> <td>Number of successes in proxied traffic (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.passive.healthy.http_statuses</code>) to consider a target healthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.threshold</code> optional </td> <td>The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Upstream for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">host_header</code> optional </td> <td>The hostname to be used as <code class="language-plaintext highlighter-rouge">Host</code> header when proxying requests through Kong.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">client_certificate</code> optional </td> <td>If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">client_certificate.id=<client_certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"client_certificate":{"id":"<client_certificate id>"}</code>.</td> </tr> </tbody> </table> <h4 id="response-58">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70", "created_at": 1422386534, "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "active": { "timeout": 1, "unhealthy": { "interval": 0, "tcp_failures": 0, "timeouts": 0, "http_failures": 0, "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505] }, "type": "http", "concurrency": 10, "headers": [{"x-another-header":["bla"], "x-my-header":["foo", "bar"]}], "healthy": { "interval": 0, "successes": 0, "http_statuses": [200, 302] }, "http_path": "/", "https_sni": "example.com", "https_verify_certificate": true }, "passive": { "type": "http", "unhealthy": { "http_statuses": [429, 500, 503], "http_failures": 0, "timeouts": 0, "tcp_failures": 0 }, "healthy": { "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308], "successes": 0 } }, "threshold": 0 }, "tags": ["user-level", "low-priority"], "host_header": "example.com", "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"} } </code></pre></div></div> <hr> <h3 id="update-or-create-upstream">Update Or Create Upstream</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-upstream">Create Or Update Upstream</h5> <div class="endpoint put indent">/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to create or update.</td> </tr> </tbody> </table> <h5 id="create-or-update-upstream-associated-to-a-specific-certificate">Create Or Update Upstream Associated to a Specific Certificate</h5> <div class="endpoint put indent">/certificates/{certificate id}/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to create or update.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to create or update.</td> </tr> </tbody> </table> <h4 id="request-body-23">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>This is a hostname, which must be equal to the <code class="language-plaintext highlighter-rouge">host</code> of a Service.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">algorithm</code> optional </td> <td>Which load balancing algorithm to use. Accepted values are: <code class="language-plaintext highlighter-rouge">"consistent-hashing"</code>, <code class="language-plaintext highlighter-rouge">"least-connections"</code>, <code class="language-plaintext highlighter-rouge">"round-robin"</code>. Default: <code class="language-plaintext highlighter-rouge">"round-robin"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on</code> optional </td> <td>What to use as hashing input. Using <code class="language-plaintext highlighter-rouge">none</code> results in a weighted-round-robin scheme with no hashing. Accepted values are: <code class="language-plaintext highlighter-rouge">"none"</code>, <code class="language-plaintext highlighter-rouge">"consumer"</code>, <code class="language-plaintext highlighter-rouge">"ip"</code>, <code class="language-plaintext highlighter-rouge">"header"</code>, <code class="language-plaintext highlighter-rouge">"cookie"</code>. Default: <code class="language-plaintext highlighter-rouge">"none"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_fallback</code> optional </td> <td>What to use as hashing input if the primary <code class="language-plaintext highlighter-rouge">hash_on</code> does not return a hash (for example, header is missing, or no Consumer identified). Not available if <code class="language-plaintext highlighter-rouge">hash_on</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. Accepted values are: <code class="language-plaintext highlighter-rouge">"none"</code>, <code class="language-plaintext highlighter-rouge">"consumer"</code>, <code class="language-plaintext highlighter-rouge">"ip"</code>, <code class="language-plaintext highlighter-rouge">"header"</code>, <code class="language-plaintext highlighter-rouge">"cookie"</code>. Default: <code class="language-plaintext highlighter-rouge">"none"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_header</code> semi-optional </td> <td>The header name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> is set to <code class="language-plaintext highlighter-rouge">header</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_fallback_header</code> semi-optional </td> <td>The header name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">header</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_cookie</code> semi-optional </td> <td>The cookie name to take the value from as hash input. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> or <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">hash_on_cookie_path</code> semi-optional </td> <td>The cookie path to set in the response headers. Only required when <code class="language-plaintext highlighter-rouge">hash_on</code> or <code class="language-plaintext highlighter-rouge">hash_fallback</code> is set to <code class="language-plaintext highlighter-rouge">cookie</code>. Default: <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">slots</code> optional </td> <td>The number of slots in the load balancer algorithm. If <code class="language-plaintext highlighter-rouge">algorithm</code> is set to <code class="language-plaintext highlighter-rouge">round-robin</code>, this setting determines the maximum number of slots. If <code class="language-plaintext highlighter-rouge">algorithm</code> is set to <code class="language-plaintext highlighter-rouge">consistent-hashing</code>, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range <code class="language-plaintext highlighter-rouge">10</code>-<code class="language-plaintext highlighter-rouge">65536</code>. Default: <code class="language-plaintext highlighter-rouge">10000</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">timeout</code> optional </td> <td>Socket timeout for active health checks (in seconds). Default: <code class="language-plaintext highlighter-rouge">1</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.interval</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.tcp_failures</code> optional </td> <td>Number of TCP failures in active probes to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.timeouts</code> optional </td> <td>Number of timeouts in active probes to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_failures</code> optional </td> <td>Number of HTTP failures in active probes (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.active.unhealthy.http_statuses</code>) to consider a target unhealthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_statuses</code> optional </td> <td>An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: <code class="language-plaintext highlighter-rouge">[429, 404, 500, 501, 502, 503,</code><code class="language-plaintext highlighter-rouge"> 504, 505]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=429&http_statuses[]=404</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.type</code> optional </td> <td>Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">concurrency</code> optional </td> <td>Number of targets to check concurrently in active health checks. Default: <code class="language-plaintext highlighter-rouge">10</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">headers</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.interval</code> optional </td> <td>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: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.successes</code> optional </td> <td>Number of successes in active probes (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.active.healthy.http_statuses</code>) to consider a target healthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">healthy.http_statuses</code> optional </td> <td>An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: <code class="language-plaintext highlighter-rouge">[200, 302]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=200&http_statuses[]=302</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">http_path</code> optional </td> <td>Path to use in GET HTTP request to run as a probe on active health checks. Default: <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">https_sni</code> optional </td> <td>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.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.active.</code><code class="language-plaintext highlighter-rouge">https_verify_certificate</code> </td> <td>Whether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Default: <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">type</code> optional </td> <td>Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, <code class="language-plaintext highlighter-rouge">http</code> and <code class="language-plaintext highlighter-rouge">https</code> options are equivalent. Accepted values are: <code class="language-plaintext highlighter-rouge">"tcp"</code>, <code class="language-plaintext highlighter-rouge">"http"</code>, <code class="language-plaintext highlighter-rouge">"https"</code>, <code class="language-plaintext highlighter-rouge">"grpc"</code>, <code class="language-plaintext highlighter-rouge">"grpcs"</code>. Default: <code class="language-plaintext highlighter-rouge">"http"</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_statuses</code> optional </td> <td>An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">[429, 500, 503]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=429&http_statuses[]=500</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.http_failures</code> optional </td> <td>Number of HTTP failures in proxied traffic (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.passive.unhealthy.http_statuses</code>) to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.timeouts</code> optional </td> <td>Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">unhealthy.tcp_failures</code> optional </td> <td>Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">healthy.http_statuses</code> optional </td> <td>An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">[200, 201, 202, 203, 204, 205,</code><code class="language-plaintext highlighter-rouge"> 206, 207, 208, 226, 300, 301,</code><code class="language-plaintext highlighter-rouge"> 302, 303, 304, 305, 306, 307,</code><code class="language-plaintext highlighter-rouge"> 308]</code>. With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">http_statuses[]=200&http_statuses[]=201</code>. With JSON, use an Array.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.passive.</code><code class="language-plaintext highlighter-rouge">healthy.successes</code> optional </td> <td>Number of successes in proxied traffic (as defined by <code class="language-plaintext highlighter-rouge">healthchecks.passive.healthy.http_statuses</code>) to consider a target healthy, as observed by passive health checks. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">healthchecks.threshold</code> optional </td> <td>The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Default: <code class="language-plaintext highlighter-rouge">0</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Upstream for grouping and filtering.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">host_header</code> optional </td> <td>The hostname to be used as <code class="language-plaintext highlighter-rouge">Host</code> header when proxying requests through Kong.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">client_certificate</code> optional </td> <td>If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is <code class="language-plaintext highlighter-rouge">client_certificate.id=<client_certificate id></code>. With JSON, use “<code class="language-plaintext highlighter-rouge">"client_certificate":{"id":"<client_certificate id>"}</code>.</td> </tr> </tbody> </table> Inserts (or replaces) the Upstream under the requested resource with the definition specified in the body. The Upstream will be identified via the <code class="language-plaintext highlighter-rouge">name or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">name or id</code> attribute has the structure of a UUID, the Upstream being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">name</code>. When creating a new Upstream without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">name</code> in the URL and a different one in the request body is not allowed. <h4 id="response-59">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-upstream">Delete Upstream</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-upstream-1">Delete Upstream</h5> <div class="endpoint delete indent">/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to delete.</td> </tr> </tbody> </table> <h5 id="delete-upstream-associated-to-a-specific-certificate">Delete Upstream Associated to a Specific Certificate</h5> <div class="endpoint delete indent">/certificates/{certificate id}/upstreams/{upstream name or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">certificate id</code> required </td> <td>The unique identifier of the Certificate to delete.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the Upstream to delete.</td> </tr> </tbody> </table> <h4 id="response-60">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 class="badge dbless" id="show-upstream-health-for-node">Show Upstream Health for Node</h3> 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 <code class="language-plaintext highlighter-rouge">data</code> field of the response contains an array of Target objects. The health for each Target is returned in its <code class="language-plaintext highlighter-rouge">health</code> field: <ul> <li>If a Target fails to be activated in the balancer due to DNS issues, its status displays as <code class="language-plaintext highlighter-rouge">DNS_ERROR</code>.</li> <li>When <a href="/gateway/2.8.x/reference/health-checks-circuit-breakers">health checks</a> are not enabled in the Upstream configuration, the health status for active Targets is displayed as <code class="language-plaintext highlighter-rouge">HEALTHCHECKS_OFF</code>.</li> <li>When health checks are enabled and the Target is determined to be healthy, either automatically or <a href="#set-target-as-healthy">manually</a>, its status is displayed as <code class="language-plaintext highlighter-rouge">HEALTHY</code>. This means that this Target is currently included in this Upstream’s load balancer execution.</li> <li>When a Target has been disabled by either active or passive health checks (circuit breakers) or <a href="#set-target-as-unhealthy">manually</a>, its status is displayed as <code class="language-plaintext highlighter-rouge">UNHEALTHY</code>. The load balancer is not directing any traffic to this Target via this Upstream.</li> </ul> When the request query parameter <code class="language-plaintext highlighter-rouge">balancer_health</code> is set to <code class="language-plaintext highlighter-rouge">1</code>, the <code class="language-plaintext highlighter-rouge">data</code> field of the response refers to the Upstream itself, and its <code class="language-plaintext highlighter-rouge">health</code> attribute is defined by the state of all of Upstream’s Targets, according to the field <code class="language-plaintext highlighter-rouge">healthchecks.threshold</code>. <div class="endpoint get indent">/upstreams/{name or id}/health/</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name or id</code> required </td> <td>The unique identifier or the name of the Upstream for which to display Target health.</td> </tr> </tbody> </table> <h4 id="request-querystring-parameters-1">Request Querystring Parameters</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">balancer_health</code> optional </td> <td>If set to 1, Kong will return the health status of the Upstream itself. See the <code class="language-plaintext highlighter-rouge">healthchecks.threshold</code> property.</td> </tr> </tbody> </table> <h4 id="response-61">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "total": 2, "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9", "data": [ { "created_at": 1485524883980, "id": "18c0ad90-f942-4098-88db-bbee3e43b27f", "health": "HEALTHY", "target": "127.0.0.1:20000", "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", "weight": 100 }, { "created_at": 1485524914883, "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890", "health": "UNHEALTHY", "target": "127.0.0.1:20002", "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", "weight": 200 } ] } </code></pre></div></div> If <code class="language-plaintext highlighter-rouge">balancer_health=1</code>: <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": { "health": "HEALTHY", "id": "07131005-ba30-4204-a29f-0927d53257b4" }, "next": null, "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9" } </code></pre></div></div> <hr> <h2 id="target-object">Target Object</h2> 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 <code class="language-plaintext highlighter-rouge">weight=0</code>; alternatively, use the <code class="language-plaintext highlighter-rouge">DELETE</code> convenience method to accomplish the same. The current target object definition is the one with the latest <code class="language-plaintext highlighter-rouge">created_at</code>. Targets can be both <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "173a6cee-90d1-40a7-89cf-0329eca780a6", "created_at": 1422386534, "upstream": {"id":"bdab0e47-4e37-4f0b-8fd0-87d95cc4addc"}, "target": "example.com:8000", "weight": 100, "tags": ["user-level", "low-priority"] } </code></pre></div></div> <h3 id="add-target">Add Target</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-target-associated-to-a-specific-upstream">Create Target Associated to a Specific Upstream</h5> <div class="endpoint post indent">/upstreams/{upstream_id}/targets</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream_id</code> required </td> <td>The unique identifier of the Upstream that should be associated to the newly-created Target.</td> </tr> </tbody> </table> <h4 id="request-body-24">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">target</code></td> <td>The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the <code class="language-plaintext highlighter-rouge">port</code> value will be overridden by the value from the DNS record.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">weight</code> optional </td> <td>The weight this target gets within the upstream load balancer (<code class="language-plaintext highlighter-rouge">0</code>-<code class="language-plaintext highlighter-rouge">65535</code>). If the hostname resolves to an SRV record, the <code class="language-plaintext highlighter-rouge">weight</code> value will be overridden by the value from the DNS record. Default: <code class="language-plaintext highlighter-rouge">100</code>.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Target for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-62">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "173a6cee-90d1-40a7-89cf-0329eca780a6", "created_at": 1422386534, "upstream": {"id":"bdab0e47-4e37-4f0b-8fd0-87d95cc4addc"}, "target": "example.com:8000", "weight": 100, "tags": ["user-level", "low-priority"] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-targets">List Targets</h3> <h5 id="list-targets-associated-to-a-specific-upstream">List Targets Associated to a Specific Upstream</h5> <div class="endpoint get indent">/upstreams/{upstream_id}/targets</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream_id</code> required </td> <td>The unique identifier of the Upstream whose Targets are to be retrieved. When using this endpoint, only Targets associated to the specified Upstream will be listed.</td> </tr> </tbody> </table> <h4 id="response-63">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "f00c6da4-3679-4b44-b9fb-36a19bd3ae83", "created_at": 1422386534, "upstream": {"id":"0c61e164-6171-4837-8836-8f5298726d53"}, "target": "example.com:8000", "weight": 100, "tags": ["user-level", "low-priority"] }, { "id": "5027BBC1-508C-41F8-87F2-AB1801E9D5C3", "created_at": 1422386534, "upstream": {"id":"68FDB05B-7B08-47E9-9727-AF7F897CFF1A"}, "target": "example.com:8000", "weight": 100, "tags": ["admin", "high-priority", "critical"] }], "next": "http://localhost:8001/targets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 id="update-target">Update Target</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> Update a target. <div class="endpoint patch indent">/upstreams/{upstream name or id}/targets/{host:port or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the upstream for which to update the target.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">host:port or id</code> required </td> <td>The host:port combination element of the target to update, or the <code class="language-plaintext highlighter-rouge">id</code> of an existing target entry.</td> </tr> </tbody> </table> <h4 id="response-64">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <hr> <h3 id="delete-target">Delete Target</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> Remove a target from the load balancer. <div class="endpoint delete indent">/upstreams/{upstream name or id}/targets/{host:port or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the upstream for which to delete the target.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">host:port or id</code> required </td> <td>The host:port combination element of the target to remove, or the <code class="language-plaintext highlighter-rouge">id</code> of an existing target entry.</td> </tr> </tbody> </table> <h4 id="response-65">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 id="set-target-address-as-healthy">Set Target Address As Healthy</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> 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 <a href="/gateway/2.8.x/reference/health-checks-circuit-breakers">health checker</a>. 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. <div class="endpoint post indent">/upstreams/{upstream name or id}/targets/{target or id}/{address}/healthy</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the upstream.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">target or id</code> required </td> <td>The host/port combination element of the target to set as healthy, or the <code class="language-plaintext highlighter-rouge">id</code> of an existing target entry.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">address</code> required </td> <td>The host/port combination element of the address to set as healthy.</td> </tr> </tbody> </table> <h4 id="response-66">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 id="set-target-address-as-unhealthy">Set Target Address As Unhealthy</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> 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. <a href="/gateway/2.8.x/reference/health-checks-circuit-breakers/#active-health-checks">Active health checks</a> 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 <a href="#delete-target">delete a target</a> instead. <div class="endpoint post indent">/upstreams/{upstream name or id}/targets/{target or id}/unhealthy</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the upstream.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">target or id</code> required </td> <td>The host/port combination element of the target to set as unhealthy, or the <code class="language-plaintext highlighter-rouge">id</code> of an existing target entry.</td> </tr> </tbody> </table> <h4 id="response-67">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 class="badge dbless" id="set-target-as-healthy">Set Target As Healthy</h3> 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 <a href="/gateway/2.8.x/reference/health-checks-circuit-breakers">health checker</a>. 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. <div class="endpoint post indent">/upstreams/{upstream name or id}/targets/{target or id}/healthy</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the upstream.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">target or id</code> required </td> <td>The host/port combination element of the target to set as healthy, or the <code class="language-plaintext highlighter-rouge">id</code> of an existing target entry.</td> </tr> </tbody> </table> <h4 id="response-68">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 class="badge dbless" id="set-target-as-unhealthy">Set Target As Unhealthy</h3> 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. <a href="/gateway/2.8.x/reference/health-checks-circuit-breakers/#active-health-checks">Active health checks</a> 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 <a href="#delete-target">delete a target</a> instead. <div class="endpoint post indent">/upstreams/{upstream name or id}/targets/{target or id}/unhealthy</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">upstream name or id</code> required </td> <td>The unique identifier or the name of the upstream.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">target or id</code> required </td> <td>The host/port combination element of the target to set as unhealthy, or the <code class="language-plaintext highlighter-rouge">id</code> of an existing target entry.</td> </tr> </tbody> </table> <h4 id="response-69">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-all-targets">List All Targets</h3> 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 <code class="language-plaintext highlighter-rouge">created_at</code> is the current definition. <div class="endpoint get indent">/upstreams/{name or id}/targets/all/</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">name or id</code> required </td> <td>The unique identifier or the name of the upstream for which to list the targets.</td> </tr> </tbody> </table> <h4 id="response-70">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "total": 2, "data": [ { "created_at": 1485524883980, "id": "18c0ad90-f942-4098-88db-bbee3e43b27f", "target": "127.0.0.1:20000", "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", "weight": 100 }, { "created_at": 1485524914883, "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890", "target": "127.0.0.1:20002", "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", "weight": 200 } ] } </code></pre></div></div> <hr> <h2 id="vaults-beta-entity">Vaults Beta Entity</h2> 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 <a href="#tags">tagged and filtered by tags</a>. <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5", "prefix": "env", "name": "env", "description": "This vault is used to retrieve redis database access credentials", "config": {"prefix":"SSL_"}, "created_at": 1422386534, "updated_at": 1422386534, "tags": ["database-credentials", "data-plane"] } </code></pre></div></div> <h3 id="add-vault">Add Vault</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-vault">Create Vault</h5> <div class="endpoint post indent">/vaults-beta</div> <h4 id="request-body-25">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">prefix</code></td> <td>The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">description</code> optional </td> <td>The description of the Vault entity.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> optional </td> <td>The configuration properties for the Vault which can be found on the vaults’ documentation page.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Vault for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-71">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5", "prefix": "env", "name": "env", "description": "This vault is used to retrieve redis database access credentials", "config": {"prefix":"SSL_"}, "created_at": 1422386534, "updated_at": 1422386534, "tags": ["database-credentials", "data-plane"] } </code></pre></div></div> <hr> <h3 class="badge dbless" id="list-vaults">List Vaults</h3> <h5 id="list-all-vaults">List All Vaults</h5> <div class="endpoint get indent">/vaults-beta</div> <h4 id="response-72">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "data": [{ "id": "518BBE43-2454-4559-99B0-8E7D1CD3E8C8", "prefix": "env", "name": "env", "description": "This vault is used to retrieve redis database access credentials", "config": {"prefix":"SSL_"}, "created_at": 1422386534, "updated_at": 1422386534, "tags": ["database-credentials", "data-plane"] }, { "id": "7C4747E9-E831-4ED8-9377-83A6F8A37603", "prefix": "env", "name": "env", "description": "This vault is used to retrieve redis database access credentials", "config": {"prefix":"SSL_"}, "created_at": 1422386534, "updated_at": 1422386534, "tags": ["certificates", "critical"] }], "next": "http://localhost:8001/vaults-beta?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" } </code></pre></div></div> <hr> <h3 class="badge dbless" id="retrieve-vault">Retrieve Vault</h3> <h5 id="retrieve-vault-1">Retrieve Vault</h5> <div class="endpoint get indent">/vaults-beta/{vaults_beta prefix or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">vaults_beta prefix or id</code> required </td> <td>The unique identifier or the prefix of the Vault to retrieve.</td> </tr> </tbody> </table> <h4 id="response-73">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5", "prefix": "env", "name": "env", "description": "This vault is used to retrieve redis database access credentials", "config": {"prefix":"SSL_"}, "created_at": 1422386534, "updated_at": 1422386534, "tags": ["database-credentials", "data-plane"] } </code></pre></div></div> <hr> <h3 id="update-vault">Update Vault</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="update-vault-1">Update Vault</h5> <div class="endpoint patch indent">/vaults-beta/{vaults_beta prefix or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">vaults_beta prefix or id</code> required </td> <td>The unique identifier or the prefix of the Vault to update.</td> </tr> </tbody> </table> <h4 id="request-body-26">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">prefix</code></td> <td>The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">description</code> optional </td> <td>The description of the Vault entity.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> optional </td> <td>The configuration properties for the Vault which can be found on the vaults’ documentation page.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Vault for grouping and filtering.</td> </tr> </tbody> </table> <h4 id="response-74">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 200 OK </code></pre></div></div> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "id": "B2A30E8F-C542-49CF-8015-FB674987D1A5", "prefix": "env", "name": "env", "description": "This vault is used to retrieve redis database access credentials", "config": {"prefix":"SSL_"}, "created_at": 1422386534, "updated_at": 1422386534, "tags": ["database-credentials", "data-plane"] } </code></pre></div></div> <hr> <h3 id="update-or-create-vault">Update Or Create Vault</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="create-or-update-vault">Create Or Update Vault</h5> <div class="endpoint put indent">/vaults-beta/{vaults_beta prefix or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">vaults_beta prefix or id</code> required </td> <td>The unique identifier or the prefix of the Vault to create or update.</td> </tr> </tbody> </table> <h4 id="request-body-27">Request Body</h4> <table> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">prefix</code></td> <td>The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities.</td> </tr> <tr> <td style="text-align: right"><code class="language-plaintext highlighter-rouge">name</code></td> <td>The name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">description</code> optional </td> <td>The description of the Vault entity.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">config</code> optional </td> <td>The configuration properties for the Vault which can be found on the vaults’ documentation page.</td> </tr> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">tags</code> optional </td> <td>An optional set of strings associated with the Vault for grouping and filtering.</td> </tr> </tbody> </table> Inserts (or replaces) the Vault under the requested resource with the definition specified in the body. The Vault will be identified via the <code class="language-plaintext highlighter-rouge">prefix or id</code> attribute. When the <code class="language-plaintext highlighter-rouge">prefix or id</code> attribute has the structure of a UUID, the Vault being inserted/replaced will be identified by its <code class="language-plaintext highlighter-rouge">id</code>. Otherwise it will be identified by its <code class="language-plaintext highlighter-rouge">prefix</code>. When creating a new Vault without specifying <code class="language-plaintext highlighter-rouge">id</code> (neither in the URL nor in the body), then it will be auto-generated. Notice that specifying a <code class="language-plaintext highlighter-rouge">prefix</code> in the URL and a different one in the request body is not allowed. <h4 id="response-75">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 201 Created or HTTP 200 OK </code></pre></div></div> See POST and PATCH responses. <hr> <h3 id="delete-vault">Delete Vault</h3> <blockquote class="note"> Note: This API is not available in DB-less mode. </blockquote> <h5 id="delete-vault-1">Delete Vault</h5> <div class="endpoint delete indent">/vaults-beta/{vaults_beta prefix or id}</div> <table class="indent"> <thead> <tr> <th style="text-align: right">Attributes</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: right"> <code class="language-plaintext highlighter-rouge">vaults_beta prefix or id</code> required </td> <td>The unique identifier or the prefix of the Vault to delete.</td> </tr> </tbody> </table> <h4 id="response-76">Response</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>HTTP 204 No Content </code></pre></div></div> <hr> </div> </div> </div> <div id="scroll-to-top-button"> </div> <div class="feedback-widget-container"> <input id="feedback-widget-checkbox" type="checkbox"> <label for="feedback-widget-checkbox"> <img src="/assets/images/icons/feedback-widget.svg" alt="Feedback widget"> </label> <div class="feedback-container"> <div class="feedback-thankyou"> Thank you for your feedback. </div> <div class="feedback-comment"> <textarea id="feedback-comment-text" rows="3" placeholder="Please let us know what we can improve on this page..."></textarea> <div class="feedback-comment-buttons"> <button id="feedback-comment-button-back">Back</button> <button id="feedback-comment-button-submit" class="button-primary">Submit</button> </div> </div> <div class="feedback-options"> <div class="feedback-options-title">Was this page useful?</div> <div class="feedback-options-buttons"> </div> </div> </div> </div> </div> <div id="image-modal" data-image-expand-disabled=""> <div class="image-modal-backdrop"></div> <div class="image-container"> <img src="" alt=""> </div> </div> <div class="modal closed" id="modal" role="dialog" aria-hidden="true" aria-labelledby="title" aria-describedby="description"> <div class="konnect-cta-card"> <div class="title"> Too much on your plate? <a href="#" class="cta-card-close modal-close" id="modal-close"> <img src="/assets/images/icons/documentation/close.svg" alt="close cta icon"> </a> </div> <div class="description"> More features, less infrastructure with Kong Konnect. 1M requests per month for free. </div> <a href="https://konghq.com/products/kong-konnect/register?utm_medium=referral&utm_source=docs&utm_campaign=gateway-konnect&utm_campaign=right-nav-card&utm_content=gateway" class="button" target="_blank" rel="noopener nofollow noreferrer "> Try it for Free </a> </div> </div> <div id="modal-open" class="modal-open"></div> <div class="modal-overlay closed" id="modal-overlay"></div> <footer class="marketing-footer--light-gray"> <section> <ul class="newsletter"> <li class="logo-wrapper"> <div class="logo"> <img src="/assets/images/logos/konglogo-light-theme-primary.svg" alt="Kong"> </div> <div class="footer-title">Powering the API world</div> Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller. <div class="footer-form-container"> <form id="subscribe-form" method="POST" action="/assets/javascripts/subscribe.js"> <input required id="subscribe-input" type="email" name="email" placeholder="Email" aria-required="true" aria-invalid="false"> <input id="footer-form-button" type="submit" form="subscribe-form" value="Subscribe"> </form> <div id="form-response"></div> </div> </li> <li class="footer-columns"> <ul class="footer-columns-product-list"> <li> <nav> <div class="footer-category">Products</div> <ul> <li> <a href="https://konghq.com/products/kong-konnect" target="_blank" rel="noopener nofollow noreferrer ">Kong Konnect</a> </li> <li> <a href="https://konghq.com/products/kong-enterprise" target="_blank" rel="noopener nofollow noreferrer ">Kong Gateway Enterprise</a> </li> <li> <a href="https://konghq.com/products/kong-gateway" target="_blank" rel="noopener nofollow noreferrer ">Kong Gateway</a> </li> <li> <a href="https://konghq.com/products/kong-mesh" target="_blank" rel="noopener nofollow noreferrer ">Kong Mesh</a> </li> <li> <a href="https://konghq.com/products/kong-ingress-controller" target="_blank" rel="noopener nofollow noreferrer ">Kong Ingress Controller</a> </li> <li> <a href="https://insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Kong Insomnia</a> </li> <li> <a href="https://konghq.com/product-updates" target="_blank" rel="noopener nofollow noreferrer ">Product Updates</a> </li> <li> <a href="https://konghq.com/contact-sales" target="_blank" rel="noopener nofollow noreferrer ">Get Started</a> </li> </ul> </nav> </li> <li> <nav> <div class="footer-category">Documentation</div> <ul> <li> <a href="/konnect/">Kong Konnect Docs</a> </li> <li> <a href="/gateway/latest/">Kong Gateway Docs</a> </li> <li> <a href="/gateway/latest/kong-enterprise/">Kong Gateway Enterprise Docs</a> </li> <li> <a href="/mesh/latest/">Kong Mesh Docs</a> </li> <li> <a href="https://docs.insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Kong Insomnia Docs</a> </li> <li> <a href="/hub/">Kong Konnect Plugin Hub</a> </li> </ul> </nav> </li> <li> <nav> <div class="footer-category">Open Source</div> <ul> <li> <a href="https://konghq.com/install/#kong-community" target="_blank" rel="noopener nofollow noreferrer ">Kong Gateway</a> </li> <li> <a href="https://kuma.io/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Kuma</a> </li> <li> <a href="https://insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Insomnia</a> </li> <li> <a href="https://konghq.com/community" target="_blank" rel="noopener nofollow noreferrer ">Kong Community</a> </li> </ul> </nav> </li> <li> <nav> <div class="footer-category">Company</div> <ul> <li> <a href="https://konghq.com/company/about-us" target="_blank" rel="noopener nofollow noreferrer ">About Kong</a> </li> <li> <a href="https://konghq.com/customers" target="_blank" rel="noopener nofollow noreferrer ">Customers</a> </li> <li> <a href="https://konghq.com/company/careers" target="_blank" rel="noopener nofollow noreferrer ">Careers</a> </li> <li> <a href="https://konghq.com/press-room" target="_blank" rel="noopener nofollow noreferrer ">Press</a> </li> <li> <a href="https://konghq.com/events" target="_blank" rel="noopener nofollow noreferrer ">Events</a> </li> <li> <a href="https://konghq.com/company/contact-us" target="_blank" rel="noopener nofollow noreferrer ">Contact</a> </li> </ul> </nav> </li> </ul> </li> </ul> </section> <section class="legal"> <div class="container d-flex"> <div class="social"> <div class="social-link"> <a href="https://www.facebook.com/konghq/" title="Facebook" target="_blank" rel="noopener nofollow noreferrer "></a> </div> <div class="social-link"> <a href="https://twitter.com/thekonginc" title="Twitter" target="_blank" rel="noopener nofollow noreferrer "></a> </div> <div class="social-link"> <a href="https://www.meetup.com/topics/kong/all/" title="Meetup" target="_blank" rel="noopener nofollow noreferrer "></a> </div> <div class="social-link"> <a href="https://linkedin.com/company/278819" title="LinkedIn" target="_blank" rel="noopener nofollow noreferrer "></a> </div> <div class="social-link"> <a href="https://github.com/kong/kong" target="_blank" class="btn-gh" title="GitHub" rel="noopener nofollow noreferrer "> </a> </div> </div> <ul> <li> <a href="https://konghq.com/legal/terms-of-use" target="_blank" rel="noopener nofollow noreferrer ">Terms</a>• <a href="https://konghq.com/legal/privacy-policy" target="_blank" rel="noopener nofollow noreferrer ">Privacy</a>• <a href="https://konghq.com/compliance" target="_blank" rel="noopener nofollow noreferrer ">Trust and Compliance</a> </li> </ul> <div> © Kong Inc. 2025 </div> </div> </section> </footer> <script> var anchorForId = function (id) { var anchor = document.createElement("a"); anchor.className = "header-link"; anchor.href = "#" + id; anchor.innerHTML = ""; anchor.title = `${id} Permalink`; return anchor; }; document.onreadystatechange = function () { if (this.readyState === "complete") { var className = ".show-anchor-links h1, .show-anchor-links h2, .show-anchor-links h3, " + ".show-anchor-links h4, .show-anchor-links h5, .show-anchor-links h6"; var headers = document.querySelectorAll(className); for (var i = 0; i < headers.length; i++) { var header = headers[i]; if (typeof header.id !== "undefined" && header.id !== "") { header.prepend(anchorForId(header.id)); } } } }; </script> <script> !function(){var i="analytics",analytics=window[i]=window[i]||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","screen","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware","register"];analytics.factory=function(e){return function(){if(window[i].initialized)return window[i][e].apply(window[i],arguments);var n=Array.prototype.slice.call(arguments);if(["track","screen","alias","group","page","identify"].indexOf(e)>-1){var c=document.querySelector("link[rel='canonical']");n.push({__t:"bpc",c:c&&c.getAttribute("href")||void 0,p:location.pathname,u:location.href,s:location.search,t:document.title,r:document.referrer})}n.unshift(e);analytics.push(n);return analytics}};for(var n=0;n<analytics.methods.length;n++){var key=analytics.methods[n];analytics[key]=analytics.factory(key)}analytics.load=function(key,n){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.setAttribute("data-global-segment-analytics-key",i);t.src="https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(t,r);analytics._loadOptions=n};analytics._writeKey="X7EZTdbdUKQ8M6x42SHHPWiEhjsfs1EQ";;analytics.SNIPPET_VERSION="5.2.0"; analytics.load("X7EZTdbdUKQ8M6x42SHHPWiEhjsfs1EQ"); analytics.page(); }}(); </script> <div id="fb-root"></div> <script id="github-bjs" src="https://buttons.github.io/buttons.js" async defer></script> <script type="text/javascript"> var _vwo_code = (function() { var account_id = 125292, settings_tolerance = 2000, library_tolerance = 2500, use_existing_jquery = true, // DO NOT EDIT BELOW THIS LINE f = false, d = document; return { use_existing_jquery: function() { return use_existing_jquery; }, library_tolerance: function() { return library_tolerance; }, finish: function() { if (!f) { f = true; var a = d.getElementById('_vis_opt_path_hides'); if (a) a.parentNode.removeChild(a); } }, finished: function() { return f; }, load: function(a) { var b = d.createElement('script'); b.src = a; b.type = 'text/javascript'; b.innerText; b.onerror = function() { _vwo_code.finish(); }; d.getElementsByTagName('head')[0].appendChild(b); }, init: function() { settings_timer = setTimeout( '_vwo_code.finish()', settings_tolerance ); this.load( '//dev.visualwebsiteoptimizer.com/j.php?a=' + account_id + '&u=' + encodeURIComponent(d.URL) + '&r=' + Math.random() ); var a = d.createElement('style'), b = '', h = d.getElementsByTagName('head')[0]; a.setAttribute('id', '_vis_opt_path_hides'); a.setAttribute('type', 'text/css'); if (a.styleSheet) a.styleSheet.cssText = b; else a.appendChild(d.createTextNode(b)); h.appendChild(a); return settings_timer; } }; })(); _vwo_settings_timer = _vwo_code.init(); </script> <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script> <script type="text/javascript"> docsearch({ appId: '05Y6TLHNFZ', apiKey: '80483bfe28d9fd036a11a6f6a06454f8', indexName: 'konghq', container: '#getkong-algolia-search-input', disableUserPersonalization: true, placeholder: 'Search the docs...', // Override selected event to allow for local environment navigation transformItems(items) { return items.map((item) => { var modifiedUrl = window.location.protocol + '//' + window.location.host + item.url.split('docs.konghq.com')[1]; return { ...item, url: modifiedUrl }; }); }, translations: { button: { buttonText: 'Search the docs..', buttonAriaLabel: 'Search the docs...' } }, resultsFooterComponent({ state }) { var facetParameters = {}; facetParameters = {"version[0]":"2.8.x","product[0]":"Kong Gateway"}; var queryParams = new URLSearchParams(facetParameters); queryParams.set('query', state.query); return { // The HTML `tag` type: 'a', ref: undefined, constructor: undefined, key: state.query, // Its props props: { href: `/search/?${queryParams.toString()}`, target: '_blank', // Raw text rendered in the HTML element children: 'See more >' }, __v: null, }; }, searchParameters: { optionalFilters: ['product:deck<score=1>', 'product:Plugin Hub<score=2>', 'product:Kong Gateway<score=3>'], facetFilters: [ 'version:2.8.x'] } }); </script> <script> (function() { if (typeof window === 'undefined') return; if (typeof window.signals !== 'undefined') return; var script = document.createElement('script'); script.src = 'https://cdn.cr-relay.com/v1/site/993c7a0d-caec-465c-be46-2d3a78ab60c5/signals.js'; script.async = true; window.signals = Object.assign( [], ['page', 'identify', 'form'].reduce(function (acc, method){ acc[method] = function () { signals.push([method, arguments]); return signals; }; return acc; }, {}) ); document.head.appendChild(script); })(); </script> </div> </body> </html>