Local development with the gateway

Frontline’s local-dev mode runs the gateway on your machine with routes and policies from a TOML file. This example puts it in front of traefik/whoami, an HTTP echo service that returns request headers. No application code is needed. A valid API key reaches the echo service with an X-Unkey-Principal header. Frontline rejects missing or invalid keys before they reach the service.

Use this example for local development only. The echo response includes the API key’s Authorization header and principal metadata. Use development keys and keep .env out of version control.

Prerequisites

You need Docker Compose, a keyspace, a root key with permission to verify keys in that keyspace, and an API key from that keyspace.

Configure the containers

Create these three files in the same directory. Replace the root key and keyspace ID in .env with your development values.

services:
  frontline:
    image: ghcr.io/unkeyed/frontline:v1.0.26-rc.1
    command: ["--config", "/etc/unkey/gateway.toml"]
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      UNKEY_ROOT_KEY: ${UNKEY_ROOT_KEY}
      UNKEY_KEYSPACE_ID: ${UNKEY_KEYSPACE_ID}
    volumes:
      - ./gateway.toml:/etc/unkey/gateway.toml:ro
    depends_on:
      - api

  api:
    image: traefik/whoami:v1.11.0

[local-dev]
http_port = 3000
root_key = "${UNKEY_ROOT_KEY}"

[[local-dev.routes]]
hostname = "localhost"
upstream = "api:80"

[[local-dev.routes.policies]]
id = "authenticate"
enabled = true
keyauth = { key_space_ids = ["${UNKEY_KEYSPACE_ID}"] }

UNKEY_ROOT_KEY=replace-with-a-root-key
UNKEY_KEYSPACE_ID=replace-with-a-keyspace-id

Only Frontline is exposed to your host, on loopback port 3000. The echo service is internal to the Compose network. Frontline uses https://api.unkey.com to verify keys by default. The authentication policy deducts one credit from keys with limited usage for each successful request. Keys with unlimited usage are unaffected.

Start the gateway

Run these commands from the directory containing the three files:

docker compose up -d
docker compose logs frontline

Inspect the forwarded headers

Set your API key in the terminal, then send a request through Frontline:

export UNKEY_API_KEY='replace-with-an-api-key-from-your-keyspace'
curl http://localhost:3000/ \
  -H "Authorization: Bearer ${UNKEY_API_KEY}"

The response includes X-Unkey-Principal, X-Forwarded-Host, and X-Forwarded-Proto: http. Header capitalization can differ. The principal’s subject is the key’s identity external ID, or its key ID if it has no identity. Send the same request without a key to check rejection:

curl -i http://localhost:3000/

Expect HTTP 401 instead of an echo response. To use your own application, replace the api service and set upstream to its Compose service name and listening port. Keep its port internal so requests cannot bypass Frontline.

Stop the example

Remove both containers and their Compose network:

docker compose down

Get started

Concepts

Build

Configure

Networking

Gateway

Observe

Local development with the gateway

Prerequisites

Configure the containers

Start the gateway

Inspect the forwarded headers

Stop the example

Next steps

The principal header

Gateway policies

​Prerequisites

​Configure the containers

​Start the gateway

​Inspect the forwarded headers

​Stop the example

​Next steps

The principal header

Gateway policies

Prerequisites

Configure the containers

Start the gateway

Inspect the forwarded headers

Stop the example

Next steps