Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Supported Installation Options
      • Supported Linux Distributions
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.1.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • FIPS 140-2
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • File Permissions Reference
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Prerequisites
  • Enable Key Authentication in Kong Manager
    • Key Authentication Configuration Parameters
  • Generate a Credential
  • Make Requests with an API Key (Client Identifier)
    • About API Key Locations in a Request
    • Make a request with the key as a query string parameter
    • Make a request with the key in a header
    • Make a request with the key in the body
Kong Gateway
3.1.x
  • Home
  • Kong Gateway
  • Kong Enterprise
  • Dev Portal
  • Applications
  • Enable Key Authentication for Application Registration
You are browsing documentation for an outdated version. See the latest documentation here.

Enable Key Authentication for Application Registration

You can use the Key Authentication plugin for authentication in conjunction with the Application Registration plugin.

The key auth plugin uses the same Client ID as generated for the Kong OAuth2 plugin. You can use the same Client ID credential for a Service that has the OAuth2 plugin enabled.

Prerequisites

  • Create a Service.
  • Enable the Application Registration plugin on a Service.
  • Activate your application for a Service if you have not already done so. The Service Contract must be approved by an Admin if auto approve is not enabled.
  • Generate a credential if you don’t want to use the default credential initially created for you.

Enable Key Authentication in Kong Manager

In Kong Manager, access the Service for which you want to enable key authentication for use with application registration:

  1. From your Workspace, in the left navigation pane, go to API Gateway > Services.
  2. On the Services page, select the Service and click View.
  3. In the Plugins pane in the Services page, click Add a Plugin.
  4. On the Add New Plugin page in the Authentication section, find the Key Authentication Plugin and click Enable.

    Key Authentication plugin panel

  5. Complete the fields as appropriate for your application. In this example, the Service is already prepopulated. Refer to the parameters described in the next section, Key Authentication Configuration Parameters, to complete the fields.

  6. Click Create.

Key Authentication Configuration Parameters

Form Parameter Description
Service The Service that this plugin configuration will target. Required.
Anonymous An optional string (Consumer UUID) value to use as an anonymous Consumer if authentication fails. If empty (default), the request fails with an 4xx. Note that this value must refer to the Consumer id attribute that is internal to Kong, and not its custom_id.
Hide Credentials Whether to show or hide the credential from the Upstream service. If true, the plugin strips the credential from the request (i.e., the header, query string, or request body containing the key) before proxying it. Default: false.
Key in Body If enabled, the plugin reads the request body (if said request has one and its MIME type is supported) and tries to find the key in it. Supported MIME types: application/www-form-urlencoded, application/json, and multipart/form-data. Default: false.
Key in Header If enabled (default), the plugin reads the request header and tries to find the key in it. Default: true.
Key in Query If enabled (default), the plugin reads the query parameter in the request and tries to find the key in it. Default: true.
Key Names Describes an array of parameter names where the plugin will look for a key. The client must send the authentication key in one of those key names, and the plugin will try to read the credential from a header, request body, or query string parameter with the same name. The key names may only contain [a-z], [A-Z], [0-9], [_] underscore, and [-] hyphen. Required. Default: apikey.
Run on Preflight Indicates whether the plugin should run (and try to authenticate) on OPTIONS preflight requests. Default: true.

Generate a Credential

Generate a Client ID credential to use as an API key. You can generate multiple credentials.

  1. In the Dev Portal > My Apps page, click View for an application.

  2. In the Authentication pane, click Generate Credential.

    Application Authentication Pane

    Now you can make requests using the Client ID as an API Key.

Make Requests with an API Key (Client Identifier)

The Client ID of your credentials can be used as an API key to make authenticated requests to a Service.

Tip: You can also access key request instructions directly within the user interface from the information icon in the Services details area of your application. Click the i icon to open the Service Details page.

Services Pane

Scroll to view all of the available examples.

Service Details Page Embedded Key Usage Instructions

About API Key Locations in a Request

Use cases for key locations:

  • Recommended: Use key_in_header (enabled by default) as the most common and secure way to do service-to-service calls.
  • If you need to share links to browser clients, use key_in_query (enabled by default). Note that query parameter requests can appear within application logs and URL browser bars, which expose the API key.
  • If you are sending a form with a browser, such as a login form, use key_in_body. This option is set to false by default because it’s a less common use case, and is a more expensive and less performant HTTP request.

For better security, only enable the key locations that you need to use.

Make a request with the key as a query string parameter

cURL
HTTPie
curl -X POST {proxy}/{route}?apikey={CLIENT_ID}
http {proxy}/{route}?apikey={CLIENT_ID}

Response (will be the same for all valid requests regardless of key location):

HTTP/1.1 200 OK
...

Make a request with the key in a header

cURL
HTTPie
curl -X POST {proxy}/{route} \
--header "apikey: {CLIENT_ID}"
http {proxy}/{route} apikey:{CLIENT_ID}

Make a request with the key in the body

cURL
HTTPie
curl -X POST {proxy}/{route} \
--data "apikey:={CLIENT_ID}"
http {proxy}/{route} apikey={CLIENT_ID}

Note: The key_in_body parameter must be set to true.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023