Connect Kong

You connect Kong through its Admin API. You route the Admin API through Kong and restrict it to Apiable, then give the connection a name, the Admin API Url and an admin Key, and run the test. The core flow works on Kong; some per-key operations are Amazon only.

Which Kong edition should you choose?

Kong Community Edition. It connects through the Kong Admin API. Select API Gateway Type also lists Kong Enterprise Edition, but that entry does not open a connect form.

Where do you connect Kong?

On the Integrations page, choose Set up on the Kong Community Edition card. Or open Integrations → API Gateways, choose + Add Gateway, select Kong Community Edition on Select API Gateway Type, and click Connect new API Gateway.

The guided setup connects Amazon API Gateway only. If you start Run the wizard as a Kong customer, its Gateway step shows Apiable doesn't connect Kong Community Edition yet. Connect Kong from its card first. The guided setup then shows Your gateway is already connected, and you continue to the next step.

How do you expose the Admin API to Apiable safely?

Route Kong's Admin API through Kong itself, as a service named admin-api on the path /admin-api. Protect it with key-auth, allow only a dedicated Apiable consumer with the acl plugin, and restrict it to Apiable's IP address.

The Admin API itself stays on loopback, with port 8001 closed to the outside, while Apiable manages consumers, credentials and plugins through an authenticated route. Run these commands against your Admin API from the Kong host. If Kong runs in DB-less mode, these commands fail; see How do you connect Kong running in DB-less mode? instead.

1. Create a service named admin-api that targets the Admin API on loopback:

curl -i -X POST http://localhost:8001/services \
  --data "name=admin-api" \
  --data "host=127.0.0.1" \
  --data "port=8001"

2. Add a route on the path /admin-api:

curl -i -X POST http://localhost:8001/services/admin-api/routes \
  --data "paths[]=/admin-api"

3. Protect the service with key-auth, so every call needs a key:

curl -i -X POST http://localhost:8001/services/admin-api/plugins \
  --data "name=key-auth"

4. Create a consumer for Apiable and issue it a key. The key value in the second response is the Key you enter in Apiable:

curl -i -X POST http://localhost:8001/consumers \
  --data "username=apiable"

curl -i -X POST http://localhost:8001/consumers/apiable/key-auth

5. Allow only that consumer on the service, with the acl plugin:

curl -i -X POST http://localhost:8001/consumers/apiable/acls \
  --data "group=apiable-admin"

curl -i -X POST http://localhost:8001/services/admin-api/plugins \
  --data "name=acl" \
  --data "config.allow=apiable-admin"

6. In Apiable, set Url to the proxied route, for example https://kong.example.com/admin-api, and Key to the key from step 4.

Use exactly admin-api as the service name and /admin-api as the path. Apiable leaves the admin-api service out of your API list, and builds the OAuth 2.0 token and authorize addresses for your subscribers by removing /admin-api from the Url.

How do you connect Kong running in DB-less mode?

Declare the admin-api route in your declarative configuration, then connect it like any Kong gateway. In DB-less mode the Admin API only reads, so the curl commands above fail. Connecting, testing and importing your services only read the Admin API, so they work.

Add these entries to the declarative configuration you load into Kong, for example kong.yml:

_format_version: "3.0"
services:
  - name: admin-api
    url: http://127.0.0.1:8001
    routes:
      - name: admin-api
        paths:
          - /admin-api
    plugins:
      - name: key-auth
      - name: acl
        config:
          allow:
            - apiable-admin
      - name: ip-restriction
        config:
          allow:
            - APIABLE_IP
consumers:
  - username: apiable
    keyauth_credentials:
      - key: YOUR_APIABLE_KEY
    acls:
      - group: apiable-admin

1. Replace YOUR_APIABLE_KEY with a long random value. In DB-less mode Kong does not generate the key, so you choose it. Keep it in your secret store, not in the file in source control.
2. Replace APIABLE_IP with Apiable's IP address. Request it from support@apiable.io.
3. Load the configuration the way you deploy Kong today. If you run Kong on Kubernetes, express the same service, route, plugins and consumer with the resources your deployment uses.
4. In Apiable, connect Kong Community Edition with Url set to the proxied route, for example https://kong.example.com/admin-api, and Key set to the value from step 1.
5. Click test. Connected means Apiable can read your Admin API.

The same names apply as above: exactly admin-api for the service and /admin-api for the path.

What works on a DB-less Kong gateway?

Everything that reads the Admin API works. Everything that writes to it does not, because DB-less Kong only takes changes through its declarative configuration. Plans and gateway-issued credentials both write to Kong today.

When a plan is bound to an Authorization Server with Client Secret Basic or Private Key JWT, the Authorization Server issues the credentials, not Kong. Contact support@apiable.io before you set up plans on a DB-less gateway, so Apiable can confirm the set-up with you. See Authorization Servers.

What does each Kong field mean?

The connect form asks for a name, the Admin API route and a key. The Key is write-only, so the form does not show it again after you save.

A trailing slash on the Url is removed when you save, so https://kong.example.com/admin-api/ is stored as https://kong.example.com/admin-api.

How do you test and save the Kong connection?

Fill in all three fields, then click the refresh icon labelled test. Apiable calls your Admin API route with the key. The result reads Connected or Unsuccessful. Then click Save Changes.

1. Enter Name, Url and Key(write-only). The test stays unavailable until all three are filled.
2. Click the refresh icon labelled test. Apiable sends a request to the Url with the apikey header.
3. Read the result: Connected means the test passed; Unsuccessful means it failed.
4. Click Save Changes. The gateway appears on the API Gateways list.

If Save Changes stays unavailable after the test reads Connected, contact support@apiable.io to finish connecting the gateway. Do not put the key in the email.

When you edit a saved Kong gateway, enter the Key again before you test or save. The form never shows the saved key.

How do you point the Kong gateway at an Authorization Server?

Open the saved gateway and go to its Authorization tab. Under OAuth handler, choose Gateway-native only or Authorization Server. Picking Authorization Server reveals a picker of your connected servers. Click Save Changes to apply.

With Gateway-native only, Kong issues OAuth 2.0 apps and JWT credentials itself. The tab also has the Level 0 API Key section and Product-level governance. See API Gateways and Authorization Servers.

Where do your Kong APIs appear after connecting?

In Catalog → API Catalog. When you save the connection, Apiable imports your Kong services, except admin-api, as APIs. You then add them to plans.

Apiable gates each plan with a Kong ACL group, so a consumer's credential only reaches the services in plans they subscribe to. When a consumer subscribes, Apiable creates a Kong consumer for the subscription with an API key, JWT credential or OAuth 2.0 app, adds it to the plan's ACL group, and applies the plan's rate limit. See APIs and coupling and Rate limits.

What does Apiable support on Kong today?

The core flow: connect the gateway, import its services as APIs, and deploy plans and subscriptions with consumers, credentials, ACL groups and rate limits. Some per-key operations and gateway reads are available on Amazon API Gateway only.

These are not available on Kong:

• Enabling or disabling an individual API key.
• Checking that a plan is set up correctly on the gateway.
• Reading usage per plan or per key from the gateway.
• Including only some resources of an API in a plan.
• Pulling API specifications with Gateway Synchronization.

Secret rotation is not available on standard setups for any gateway. To replace a subscription's credentials on Kong, use Regenerate Credentials: Apiable revokes the current credentials and issues new ones. See Credentials.

Troubleshooting

Match what you see to the fix.

Where to next