FreeKB - Kong Getting Started with Kong
Getting Started with Kong

Kong is a service that sits between a client and a server. A server could be any type of server that serves content, such as a web server, an application server, an FTP server, et cetera.

For example, let's say you have a web server that produces HTML web pages. Requests for HTML web pages can be sent through Kong. The following is the bare minimum that would need to be done to route requests through Kong.

Create a Service

Let's say you want to route requests for through Kong. In this scenario, you could create a service named "example-service".


Create a Route

Then you could create a route that routes requests for "example-service" to


GET through Kong

You should now be able to get an HTML web pages from the web server through Kong. 

curl -v -X GET "http://localhost:8001/" --header "Host:"


If the request is successful, you should get something like this. The -v option shows the request for was responded by Kong.

> Host:
< Via: kong/2.0.1

    <h1>Example Domain</h1>
    <p>This domain is for use in illustrative examples in documents. You may use this
    domain in literature without prior coordination or asking for permission.</p>
    <p><a href="">More information...</a></p>


Configure a Plugin

Plugins are used to allow or deny a request. One or more plugins can be associated with a service . . .


Like this.

curl -X POST "http://localhost:8001/services/example-service/plugins" . . .


. . . or with a route.


Like this.

curl -X POST "http://localhost:8001/routes/route-id/plugins" . . .


Two commonly used plugins are:

  • acl (access control list)
  • key-auth (key based authentication)

In this example, the ACL plugin and key-auth plugin are associated with "example-service".

curl -X POST "http://localhost:8001/services/example-service/plugins" --data "name=acl" --data "config.whitelist=example-group"

curl -X POST "http://localhost:8001/services/example-service/plugins" --data "name=key-auth"


With this setup, a request will only be allowed when:

  • The consumer is in "example-group"
  • The consumer presents the appropriate key-auth key for authentication

Attempting to get through Kong from a consumer not in "example-group" and without the appropriate key for authentication . . .

curl -v -X GET "http://localhost:8001/" --header "Host:"


. . . should return this header.

< HTTP/1.1 403 Forbidden


And this message.

 "message":"No API key found in request" 


An examination of the header will show no API key in the request.

> GET / HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.44 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Accept: */*
> Host:


Let's say you try the request with some random API key.

curl -v -X GET "http://localhost:8001/" --header "Host:" --header "apikey: abc123"


Now the request includes an API key.

> GET / HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.44 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Accept: */*
> Host:
> apikey:abc123


But the following is returned, because no consumers have been setup with the apikey.

 "message":"You cannot consume this service" 



In this scenario, a consumer will need to be a member of the acl group that has been whitelisted and the consumer will need to include the key-auth key when submitting a request to example-service.


Let's create a consumer named john.doe.

curl -X POST "http://localhost:8001/consumers/" --data "username=john.doe"


Make john.doe a member of example-group.

curl -X POST "http://localhost:8001/consumers/john.doe/acls" --data "group=example-group"


provision john.doe with an API Key

curl -X POST "http://localhost:8001/consumers/john.doe/key-auth" --data "key=abc123"


Now, you should be able to get an HTML web pages from the web server through Kong by providing the API Key. In this example, the the API Key is "abc123".

curl -v -X GET "http://localhost:8001/" --header "Host:" --header "apikey:abc123"


The -v option will show that API Key was sent in the request.

> apikey:abc123
> Host:


If the GET request is successful, the HTML page should be display. On the other hand, if an invalid API Key is used in the request, the following should be displayed.

 "message":"Invalid authentication credentials" 


Add a Comment

We will never share your name or email with anyone. Enter your email if you would like to be notified when we respond to your comment.

Please enter 7243f in the box below so that we can be sure you are a human.


Web design by yours truely - me, myself, and I   |   |