Local development

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)"

Last modified on August 12, 2026

⌘I

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Send a Principal with curl

Use a Principal file

​Send a Principal with curl

​Use a Principal file

Send a Principal with curl

Use a Principal file