The principal header

When an API key authentication policy a key, the gateway tells your who’s calling in the X-Unkey-Principal request header, as JSON. Your code reads this one header instead of calling Unkey. If the header is missing, no key was verified for that request.

What’s in the header

{
  "version": "v1",
  "subject": "user_123",
  "type": "API_KEY",
  "identity": {
    "externalId": "user_123",
    "meta": { "plan": "pro" }
  },
  "source": {
    "key": {
      "keyId": "key_2ZSM3h",
      "keySpaceId": "ks_1234abcd",
      "name": "production laptop",
      "expiresAt": 1767225600000,
      "credits": 41,
      "meta": { "region": "eu" },
      "roles": ["editor"],
      "permissions": ["documents.read", "documents.write"]
    }
  }
}

string

required

Format version, currently v1. It only changes if a field is removed, renamed, or changes type. New optional fields can appear without a version change, so ignore fields you don’t know.

string

required

Who’s calling. For a key linked to an identity, it’s the identity’s externalId, so all keys of one identity share it. Otherwise it’s the key ID.

string

required

How the caller authenticated. Always API_KEY today. Treat any other value as unknown.

object

The identity the key is linked to. Left out when the key has none. externalId is the ID you assigned, and meta is the identity’s metadata ({} when empty).

object

required

The verified key.

keyId and keySpaceId: always present.
name: left out when the key has no name.
expiresAt: Unix milliseconds, left out when the key doesn’t expire. Always in the future, because expired keys are rejected.
credits: credits left after this request. Left out for unlimited keys, so 0 means this request used the last one.
meta: the key’s metadata ({} when empty).
roles and permissions: the key’s roles and permissions, left out when empty. The policy’s permission query has already passed, so use these for finer checks in your app.

Read it in your app

Parse the header as JSON, and expect optional fields to be missing.

import { Hono } from "hono";

type Principal = {
  version: string;
  subject: string;
  type: "API_KEY" | string;
  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<{ Variables: { principal: Principal } }>();

app.use("*", async (c, next) => {
  const raw = c.req.header("x-unkey-principal");
  if (!raw) {
    return c.json({ error: "unauthenticated" }, 401);
  }
  c.set("principal", JSON.parse(raw) as Principal);
  await next();
});

app.get("/documents", (c) => {
  const principal = c.get("principal");
  if (!principal.source.key?.permissions?.includes("documents.read")) {
    return c.json({ error: "forbidden" }, 403);
  }
  return c.json({ owner: principal.subject });
});

import { NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
  const raw = req.headers.get("x-unkey-principal");
  if (!raw) {
    return NextResponse.json({ error: "unauthenticated" }, { status: 401 });
  }
  const principal = JSON.parse(raw);
  return NextResponse.json({ owner: principal.subject, plan: principal.identity?.meta?.plan });
}

type Principal struct {
	Version  string `json:"version"`
	Subject  string `json:"subject"`
	Type     string `json:"type"`
	Identity *struct {
		ExternalID string         `json:"externalId"`
		Meta       map[string]any `json:"meta"`
	} `json:"identity,omitempty"`
	Source struct {
		Key *struct {
			KeyID       string         `json:"keyId"`
			KeySpaceID  string         `json:"keySpaceId"`
			Name        *string        `json:"name,omitempty"`
			ExpiresAt   *int64         `json:"expiresAt,omitempty"`
			Credits     *int64         `json:"credits,omitempty"`
			Meta        map[string]any `json:"meta"`
			Roles       []string       `json:"roles,omitempty"`
			Permissions []string       `json:"permissions,omitempty"`
		} `json:"key,omitempty"`
	} `json:"source"`
}

func handler(w http.ResponseWriter, r *http.Request) {
	raw := r.Header.Get("X-Unkey-Principal")
	if raw == "" {
		http.Error(w, "unauthenticated", http.StatusUnauthorized)
		return
	}
	var p Principal
	if err := json.Unmarshal([]byte(raw), &p); err != nil {
		http.Error(w, "bad principal", http.StatusBadRequest)
		return
	}
	fmt.Fprintf(w, "hello %s", p.Subject)
}

Why you can trust it

The header isn’t signed, but callers can’t fake it. The gateway removes any X-Unkey-* header a client sends, and only then sets X-Unkey-Principal. Compute deployments can only be reached through the gateway, so inside your app the header is always real. If you run the same code somewhere else, for example during local development, anyone who can reach it can send a fake header. If several API key policies match a request, the first one that succeeds sets the principal. You can rate limit by the principal: authenticatedSubject counts by subject, and principalField counts by a field such as source.key.meta.org_id. Only string values work. See Rate limit policy.

Get started

Concepts

Build

Configure

Networking

Gateway

Observe

The principal header

What’s in the header

Read it in your app

Why you can trust it

Next steps

Local development with the gateway

API key authentication policy

​What’s in the header

​Read it in your app

​Why you can trust it

​Next steps

Local development with the gateway

API key authentication policy

What’s in the header

Read it in your app

Why you can trust it

Next steps