Skip to main content

Documentation Index

Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt

Use this file to discover all available pages before exploring further.

engine.Principal is the shared identity shape produced by authentication policies. It decouples the authentication mechanism from downstream authorization decisions and from upstream applications, which receive it as a JSON payload on the X-Unkey-Principal header. The struct is hand-written with encoding/json rather than generated from protobuf. The Principal is output-only (sentinel produces it, apps consume the JSON), so proto-as-IDL buys nothing while fighting the JSON contract we want to expose. The wire format is authoritative. For the full public reference, see the product docs.

​
Fields

​
version
string
Schema version of the Principal payload. Currently "v1". Bumped only on breaking changes to the JSON shape.
​
subject
string
The primary identifier of the authenticated entity. For KeyAuth, this is the identity’s external ID when the key is linked to an identity, otherwise the key ID. For JWTAuth, this is the configured subject claim (default sub).
​
type
PrincipalType
Which authentication method produced this Principal. API_KEY or JWT. Always matches the populated variant of source.
​
identity
Identity
The Unkey identity linked to the credential, when present. Absent from the JSON entirely when no identity is linked — never null and never an empty object.
​
source
Source
Discriminated union over method-specific detail. Contains exactly one populated variant matching type: source.key for API keys, source.jwt for JWT. The variant name is the lowercase of the type (minus the underscore).

​
What a principal looks like

{
  "version": "v1",
  "subject": "user_abc123",
  "type": "API_KEY",
  "identity": {
    "externalId": "user_abc123",
    "meta": { "plan": "pro" }
  },
  "source": {
    "key": {
      "keyId": "key_xyz",
      "keySpaceId": "ks_abc123",
      "name": "ACME Production",
      "expiresAt": 1717200000000,
      "meta": {},
      "roles": ["admin"],
      "permissions": ["api.read", "api.write"]
    }
  }
}

​
KeyAuth source fields

When produced by a KeyAuth policy, source.key carries the verified key detail. Fields marked optional are omitted from the JSON when unset.
FieldOptionalDescription
keyIdThe ID of the verified key.
keySpaceIdThe keyspace the key belongs to.
nameyesHuman-readable key name, when set.
expiresAtyesUnix timestamp in milliseconds (JSON number). Omitted when the key has no expiry.
metaCustom key metadata. Always emitted, {} when empty.
rolesyesRaw RBAC role names. Omitted when empty.
permissionsyesRaw RBAC permissions. Omitted when empty.

​
Header propagation

Sentinel serializes the principal to JSON and sets it on the X-Unkey-Principal header before forwarding to the instance. The instance reads this header to make authorization decisions without re-verifying the credential. The proxy handler strips any incoming X-Unkey-Principal header before policy evaluation to prevent clients from spoofing an authenticated identity.