Protect with API keys

The api-key auth mode requires every incoming request to present a bearer token. Tokens are issued by you, scoped to a single application, and verified at Caddy on the serving device before any request reaches your workload.

Switch the application to api-key

Find the access entry you want to protect and update its policy:

app.yml

policies:
  auth: { mode: none }
  auth: { mode: api-key }

edgible stack deploy -f app.yml

From this point, requests without a valid bearer token receive 401 Unauthorized. Requests with one are forwarded to your workload.

Issue a key

edgible application api-keys create \
  --app-id <app-id> \
  --name "ci-deploy"

Output includes the key value — save it now. It’s not shown again.

Key created.
  ID:        ak_a1b2c3d4
  Name:      ci-deploy
  Token:     edg_live_d4e5f6a7b8c9...   (save this — it will not be shown again)
  Expires:   never

To set an expiry:

edgible application api-keys create \
  --app-id <app-id> \
  --name "vendor-integration" \
  --expires 2026-12-31

Use the key

Send the token in the Authorization header:

curl https://api.example.com/v1/things \
  -H "Authorization: Bearer edg_live_d4e5f6a7b8c9..."

Caddy verifies it against the list pushed to the agent, and forwards the request to your workload. Your workload sees no Authorization header difference; it just receives the request.

List, rotate, revoke

# See the keys for an application (token bodies are not shown).
edgible application api-keys list --app-id <app-id>

# Delete a single key (it stops working immediately).
edgible application api-keys delete --app-id <app-id> --key-id ak_a1b2c3d4

Rotation is a manual two-step: create a new key, update consumers, delete the old key. There’s no in-place rotation.

Choosing key names

The --name is what shows up in api-keys list and what you’ll see when auditing. Use names that describe who or what uses the key, not what it does. ci-deploy, monitoring-pinger, vendor-acme-prod are good. production, key1, temp are bad.

When to use short-code instead

If you want to share access with a person for a defined window — a contractor for a week, a client demo for a day — short-code is the better fit. Short codes have built-in expiry and use-count limits, and toggling them off is one CLI call.

edgible application short-codes create \
  --app-id <app-id> \
  --name "demo-2026-04" \
  --expires 2026-04-30T18:00:00Z \
  --max-uses 100

See Authentication modes for the full distinction.