Local development

Test your application’s Principal header handling locally without running the gateway. Mock the identity object for local development and testing.

Deploying applications on Unkey is in public beta. To try it, select Projects in the dashboard sidebar and create a project. Deployed resources are free until August 1, 2026. We’re eager for feedback, so let us know what you think on Discord, X, or email [e-mail].

The Principal is plain JSON with no encryption or signing. During local development, you can set the X-Unkey-Principal header yourself to test your application’s authentication handling without running the gateway.

The X-Unkey-Principal header has no cryptographic signature. When you deploy to Unkey, the gateway always sits in front of your app and strips any client-supplied header before setting its own. Traffic cannot reach your API without going through the gateway, so forged headers are not a concern.

If you self-host or expose your app through other infrastructure (direct port-forward, misconfigured ingress, or similar), anyone who reaches it directly can forge the header. Never expose your app to untrusted traffic without the gateway in front of it.

Send a Principal with curl

Pass the Principal as a JSON string in the header:

curl http://localhost:8080/api/resource \
  -H 'X-Unkey-Principal: {"version":"v1","subject":"test_user","type":"API_KEY","source":{"key":{"keyId":"key_test","keySpaceId":"ks_test","meta":{},"roles":["admin"],"permissions":["api.read","api.write"]}}}'

Use a Principal file

For repeated testing, store the Principal in a file and reference it. This keeps your curl commands readable and makes it easy to switch between test scenarios.

cat > principal.json << 'EOF'
{
  "version": "v1",
  "subject": "test_user",
  "type": "API_KEY",
  "identity": {
    "externalId": "test_user",
    "meta": { "plan": "pro" }
  },
  "source": {
    "key": {
      "keyId": "key_test",
      "keySpaceId": "ks_test",
      "meta": {},
      "roles": ["admin"],
      "permissions": ["api.read", "api.write"]
    }
  }
}
EOF

curl http://localhost:8080/api/resource \
  -H "X-Unkey-Principal: $(cat principal.json | jq -c)"