Local development with the gateway

When you run your locally, there’s no gateway in front of it, so your code gets no X-Unkey-Principal header. You can send one yourself to test the code that reads it.

Test your app locally

The principal header is JSON. Put it in the header value of your request:

curl http://localhost:8080/documents \
  -H 'X-Unkey-Principal: {"version":"v1","subject":"user_123","type":"API_KEY","source":{"key":{"keyId":"key_local","keySpaceId":"ks_local","meta":{},"permissions":["documents.read"]}}}'

To test several callers, keep one JSON file per caller and send it with jq -c. It also catches invalid JSON before the request goes out.

cat > principal-pro-user.json <<'EOF'
{
  "version": "v1",
  "subject": "user_123",
  "type": "API_KEY",
  "identity": { "externalId": "user_123", "meta": { "plan": "pro" } },
  "source": {
    "key": {
      "keyId": "key_local",
      "keySpaceId": "ks_local",
      "meta": {},
      "roles": ["editor"],
      "permissions": ["documents.read", "documents.write"]
    }
  }
}
EOF

curl http://localhost:8080/documents \
  -H "X-Unkey-Principal: $(jq -c . principal-pro-user.json)"

Your code will see all of these in production, so test them too:

No identity. The key isn’t linked to an identity.
No credits. The key has unlimited usage.
No roles or permissions. The key has none attached.
No header at all. This is what a request to an unauthenticated route looks like.

See the principal header for every field.

The header isn’t signed. On Unkey, only the gateway can set it. If your app can be reached any other way, anyone can send a fake one. Only trust the header on traffic that came through Unkey.

Test your policies

To test your policies, deploy to a preview and call its preview domain. Preview and production have separate policy lists. A policy change only applies on a new deployment.

Next steps

The principal header

Every field and when it’s omitted.

Gateway policies

Add authentication, rate limits, and other rules to your app.

Last modified on September 29, 2026

⌘I

Get started

Concepts

Build

Configure

Networking

Gateway

Observe

Local development with the gateway

Test your app locally

Test your policies

Next steps

The principal header

Gateway policies

​Test your app locally

​Test your policies

​Next steps

The principal header

Gateway policies

Test your app locally

Test your policies

Next steps