> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how the Sentinel reverse proxy authenticates incoming requests and forwards verified identity information to your application.

<Info>
  Unkey Deploy is in public beta. To try it, open the product switcher in the
  top-left of the dashboard and select **Deploy**. During beta, deployed
  resources are free. We're eager for feedback, so let us know what you think
  on [Discord](https://unkey.com/discord), [X](https://x.com/unkeydev), or
  email [support@unkey.com](mailto:support@unkey.com).
</Info>

Authentication policies verify credentials before requests reach your app. On success, the Sentinel produces a [Principal](/platform/sentinel/principal/overview), a verified identity object, and forwards it to your app via the `X-Unkey-Principal` request header. Your app receives the authenticated identity without performing its own credential checks.

The Sentinel supports [API key authentication](/platform/sentinel/policies/api-key) today, with JWT coming soon. All authentication methods produce the same [Principal structure](/platform/sentinel/principal/overview), so your app handles identity the same way regardless of how the request was authenticated.

## How it works

```mermaid theme={"theme":"kanagawa-wave"}
sequenceDiagram
    participant C as Client
    participant S as Sentinel
    participant A as Your App

    C->>S: Request with credentials
    S->>S: Strip any existing X-Unkey-Principal header
    S->>S: Evaluate authentication policy
    alt Credentials valid
        S->>S: Build Principal from verified identity
        S->>A: Forward request with X-Unkey-Principal header
        A->>A: Parse Principal, read subject and source
        A->>C: Response
    else Credentials invalid or missing
        S->>C: 401 Unauthorized
    end
```

After all policies pass, the Sentinel serializes the Principal as JSON and sets the `X-Unkey-Principal` header on the proxied request. The Sentinel always strips any client-supplied `X-Unkey-Principal` header before policy evaluation, so clients can't forge identity information. Since all traffic to your deployment routes through the Sentinel, you can trust the header unconditionally.

Only one Principal exists per request. If multiple authentication policies match, the first successful one sets the Principal and subsequent policies are skipped. Configuring multiple policies lets a caller authenticate with either method (for example, an API key or a JWT), but sending both on the same request is not meaningful: only the first successful policy produces the Principal, and the other credential is ignored.

## The Principal

Your app reads the authenticated identity from the `X-Unkey-Principal` request header. If the header is absent, the request is anonymous. Here's an example for an API key linked to an identity:

```json theme={"theme":"kanagawa-wave"}
{
  "version": "v1",
  "subject": "user_42",
  "type": "API_KEY",
  "identity": {
    "externalId": "user_42",
    "meta": { "plan": "pro" }
  },
  "source": {
    "key": {
      "keyId": "key_3xMpL9kF2nR",
      "keySpaceId": "ks_abc123",
      "meta": {},
      "roles": ["admin"],
      "permissions": ["api.read", "api.write"]
    }
  }
}
```

See the [Principal reference](/platform/sentinel/principal/overview) for the full field definitions, the [API key source](/platform/sentinel/principal/sources/api-key) page for source-specific details, and [framework examples](/platform/sentinel/principal/examples) for integration patterns.

## Downstream policies

Other policies can use the Principal for their own decisions without knowing which authentication method produced it. For example, a [rate limit policy](/platform/sentinel/policies/rate-limiting) can throttle requests per `subject`, and an API key policy can enforce [permissions](/platform/apis/features/authorization/introduction) before requests reach your app. This decoupling means you can swap authentication methods without reconfiguring downstream policies.