Skip to main content
sentinel.v1.Principal is the shared identity shape produced by authentication policies. It decouples the authentication mechanism from downstream authorization decisions.

​
Fields

​
subject
string
The authenticated identity string. For KeyAuth, this is the external ID (if present) or the key ID.
​
type
PrincipalType
The authentication method that produced this principal. Values: PRINCIPAL_TYPE_API_KEY, PRINCIPAL_TYPE_BASIC, PRINCIPAL_TYPE_JWT.
​
claims
map<string, string>
Key-value metadata from the auth policy. Contents vary by policy type.

​
What a principal looks like

{
  "subject": "user_abc123",
  "type": "PRINCIPAL_TYPE_API_KEY",
  "claims": {
    "key_id": "key_xyz",
    "key_space_id": "ks_abc123",
    "api_id": "api_456",
    "workspace_id": "ws_789",
    "external_id": "user_abc123",
    "meta": "{\"plan\": \"pro\"}"
  }
}

​
KeyAuth claims

When produced by a KeyAuth policy, the principal includes these claims:
ClaimDescription
key_idUnkey key identifier
key_space_idKeyspace the key belongs to
api_idAPI identifier
workspace_idWorkspace identifier
nameKey name (if set)
identity_idIdentity ID (if set)
external_idExternal ID (if set)
metaKey metadata JSON (if set)
expiresExpiration time in RFC 3339 format (if set)

​
Header propagation

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