Local development - Unkey Docs

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.

Warning

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"]    }  }}EOFcurl http://localhost:8080/api/resource \  -H "X-Unkey-Principal: $(cat principal.json | jq -c)"