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.
To verify real API keys and let Frontline generate the header, run the
local gateway with Docker Compose.
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:
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.
