These examples show how to parse the Principal from the X-Unkey-Principal header in common frameworks using API key authentication.
import { Hono } from "hono";type KeyPrincipal = { version: string; subject: string; type: "API_KEY"; identity?: { externalId: string; meta: Record<string, unknown>; }; source: { key: { keyId: string; keySpaceId: string; name?: string; expiresAt?: number; credits?: number; meta: Record<string, unknown>; roles?: string[]; permissions?: string[]; }; };};const app = new Hono();app.use("*", async (c, next) => { const header = c.req.header("x-unkey-principal"); if (!header) { return c.json({ error: "Not authenticated" }, 401); } const principal: KeyPrincipal = JSON.parse(header); c.set("principal", principal); await next();});app.get("/api/resource", (c) => { const principal = c.get("principal") as KeyPrincipal; if (!principal.source.key.permissions?.includes("api.read")) { return c.json({ error: "Insufficient permissions" }, 403); } const userId = principal.subject; const org = principal.identity?.meta?.org; return c.json({ userId, org });});export default app;