# Authentication & permissions

> Cookie sessions with CSRF, role and permission checks, admin impersonation and the audit trail.

## Cookie sessions, not bearer tokens

Slicekit authenticates browsers with **HTTP-only cookie sessions**, which keeps tokens out of
JavaScript and out of `localStorage`. Because cookies are sent automatically, every state-changing
request is also protected against CSRF with a token the frontend echoes back.

The frontend never handles a raw credential; the typed API client attaches the cookie and the CSRF
header for you. See [the API client](/docs/api-client).

## Authorization

Authorization is permission-based. Endpoints declare the permission they require, and a check runs
before the handler:

```csharp
app.MapPost("/api-keys", CreateApiKeyEndpoint.Handle)
   .RequirePermission(Allow.UserCreateApiKey);
```

There are no roles: permissions are granted individually from a single catalog (the `Allow` class),
and API keys carry their own scoped subset. A bulk permissions endpoint lets an admin grant or
revoke many at once; the change is audited.

## Admin impersonation

Support staff sometimes need to see exactly what a user sees. Slicekit includes **short-lived, audited
impersonation**: an admin with the right permission can start a session as another user. The session
is time-boxed, clearly flagged, and every impersonated action is recorded in the audit trail.

## Audit trail

Security-relevant actions (sign-in, permission changes, impersonation, sensitive mutations) emit
**audit events**. These flow through the same Serilog → OTLP → Loki pipeline as the rest of the logs,
so there is no audit table to maintain and retention lives in Loki rather than the database.

## Behind a reverse proxy

In production the API runs behind a reverse proxy, so it is configured to trust forwarded headers for
the scheme and client address. That keeps redirects, cookie `Secure` flags and audited IP addresses
correct when TLS terminates at the proxy.

## What you configure

- **Roles and their permissions.** Seed the set your product needs.
- **Session lifetime and cookie options.** Sensible secure defaults are provided.
- **Which actions are audited.** Emit an audit event from any handler that warrants one.