Track API requests by Consumer with Metering & Billing

Uses: Kong Gateway deck

Incompatible with

konnect

Prerequisites

Kong Gateway running

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

Copied!

Run the quickstart script:

curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA

Copied!

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

decK v1.43+

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

Required entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

Run the following command:

echo '
_format_version: "3.0"
services:
  - name: example-service
    url: http://httpbin.konghq.com/anything
routes:
  - name: example-route
    paths:
    - "/anything"
    service:
      name: example-service
    protocols:
    - http
    - https
' | deck gateway apply -

Copied!

To learn more about entities, you can read our entities documentation.

Konnect system account token

You need a Konnect system account token (spat_) with the Ingest role for Metering. This token authenticates the plugin when it sends events to the Konnect ingest endpoint.

Export your system account token:

export DECK_AUTH_TOKEN='YOUR SPAT TOKEN'

Copied!

For more information, see system accounts and access tokens.

You can track per-consumer API usage without modifying your upstream services by using the Metering & Billing plugin. The plugin emits a CloudEvent for every API request that passes through Kong Gateway, using the authenticated Consumer as the billable subject.

In this guide, you’ll:

Create a Consumer with a Key Auth credential
Configure Key Authentication on the example Service
Configure the Metering & Billing plugin to emit usage events to Konnect
Verify that usage events appear in the Konnect UI

Create a Consumer

Consumers can represent the clients that call your APIs. The Metering & Billing plugin uses the Consumer’s username as the subject field in each CloudEvent it emits, which enables per-client billing downstream.

echo '
_format_version: "3.0"
consumers:
  - username: alice
    keyauth_credentials:
    - key: alice-key
' | deck gateway apply -

Copied!

Configure Key Authentication

This Metering & Billing plugin configuration requires an authenticated Consumer to be present on each request. Enable the Key Auth plugin on the example Service:

echo '
_format_version: "3.0"
plugins:
  - name: key-auth
    service: example-service
    config:
      key_names:
      - apikey
' | deck gateway apply -

Copied!

Configure the Metering & Billing plugin

Enable the Metering & Billing plugin on the example Service. Setting meter_api_requests: true tells the plugin to emit one event per request. Setting subject.look_up_value_in: consumer populates the subject field in each CloudEvent with the authenticated Consumer’s username.

echo '
_format_version: "3.0"
plugins:
  - name: metering-and-billing
    service: example-service
    config:
      ingest_endpoint: https://us.api.konghq.com/v3/openmeter/events
      api_token: "${{ env "DECK_AUTH_TOKEN" }}"
      meter_api_requests: true
      meter_ai_token_usage: false
      subject:
        look_up_value_in: consumer
' | deck gateway apply -

Copied!

Validate

Send a few requests through the example Service using the alice Consumer’s API key:

for _ in {1..3}; do
  curl -i http://localhost:8000/anything \
       -H "apikey: alice-key"
  echo
done

Copied!

This sends three requests, each emitting a CloudEvent with subject: alice to Konnect.

Now verify that the events were received:

In the Konnect sidebar, click Metering & Billing.
Click the Events tab.

You’ll see three events listed, each with subject: alice, one for each request that passed through Kong Gateway.

You’ll also see an error message like no customer found for event subject: consumer associated with the event. This is expected since we’re only tracking API usage. If you want to meter and bill Consumer’s usage, see Metering, Customers and usage attribution, and Billing, invoicing, and subscriptions.

Cleanup

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

Copied!

Track API requests by Consumer with Metering & Billing

Prerequisites

Kong Gateway running

decK v1.43+

Required entities

Konnect system account token

Create a Consumer

Configure Key Authentication

Configure the Metering & Billing plugin

Validate

Cleanup

Destroy the Kong Gateway container

Help us make these docs great!

Still need help?