# Backends: transports and strategies

A backend is **`AuthenticationBackend(name, transport, strategy)`**. Transports read tokens from the request; strategies interpret and persist them.

```mermaid
flowchart LR
  REQ[HTTP request]
  T[Transport]
  S[Strategy]
  UM[User manager / DB]
  REQ --> T
  T -->|token bytes| S
  S -->|user id| UM
```

## Transports

| Transport | Typical use |
| --------- | ----------- |
| `BearerTransport` | APIs, SPAs with `Authorization: Bearer`. |
| `CookieTransport` | Browser sessions; pairs with CSRF for unsafe methods (see [Security](../security.md)). |
| `ApiKeyTransport` | Machine clients via `Authorization: Bearer ak_…`, `X-API-Key`, or signed `LSA1-HMAC-SHA256` requests (see [API keys](../guides/api_keys.md)). |

## Strategies

| Strategy | Behavior |
| -------- | -------- |
| `JWTStrategy` | Stateless access tokens; optional `jti` denylist; optional session fingerprint claim. |
| `DatabaseTokenStrategy` | Opaque tokens stored in DB (keyed digest at rest; legacy plaintext opt-in only). |
| `RedisTokenStrategy` | Opaque tokens in Redis (`litestar-auth[redis]`). |
| `ApiKeyStrategy` | Validates API keys (and optional HMAC signatures) against the configured store; sets `request.auth` to `ApiKeyContext` on success. |

Constructors and options are documented under [Python API — Strategies](../api/strategies.md).

## Opaque DB-token setup

For the common bearer + database-token plugin flow, prefer the plugin-owned preset instead of hand-assembling the backend:

```python
from litestar_auth import DatabaseTokenAuthConfig, LitestarAuthConfig
from litestar_auth.manager import UserManagerSecurity

config = LitestarAuthConfig(
    database_token_auth=DatabaseTokenAuthConfig(
        token_hash_secret="replace-with-32+-char-db-token-secret",
    ),
    user_model=YourUserModel,
    user_manager_class=YourUserManager,
    session_maker=session_maker,
    user_manager_security=UserManagerSecurity(
        verification_token_secret="replace-with-32+-char-secret",
        reset_password_token_secret="replace-with-32+-char-secret",
    ),
)
```

`session_maker` here is any callable object compatible with `session_maker() -> AsyncSession`; `async_sessionmaker(...)` is the usual implementation, not the only supported one.
Manager-scoped secrets, shared `PasswordHelper` injection, runtime password validation, and app-owned
schema helper reuse still follow the same
[configuration contract](../configuration/manager.md#manager-password-surface). Keep
manager secrets on `user_manager_security`; use `user_manager_factory` when a custom manager
constructor needs custom inputs.

At runtime this still becomes a normal `AuthenticationBackend`, but the preset keeps request-session binding and migration-only rollout flags on the plugin side.

## Order and multiple backends

- Middleware tries backends **in order**; the first that yields a user wins.
- The **first** backend is exposed under the configured `auth_path` (default `/auth`).
- **Additional** backends are mounted under `/auth/{backend-name}/...` so paths do not collide.
- Manual `AuthenticationBackend(...)` assembly remains the direct path for multi-backend or custom transport setups.

Name backends explicitly when you have more than one:

```python
AuthenticationBackend(name="api", transport=BearerTransport(), strategy=jwt_strategy)
AuthenticationBackend(name="mobile", transport=BearerTransport(), strategy=db_strategy)
```

## Choosing a stack

- **Public API / microservice:** often `BearerTransport` + `JWTStrategy` with a durable denylist in production if you rely on revocation.
- **Same-site browser app:** `CookieTransport` + strategy of your choice; enable CSRF for state-changing requests.
- **Central session store:** use `LitestarAuthConfig(..., database_token_auth=DatabaseTokenAuthConfig(...))` for the plugin-managed bearer + DB-token path, or `RedisTokenStrategy` when Redis is your session store. Drop to manual `DatabaseTokenStrategy` assembly only when you need a custom transport or multiple backends.
- **Service-to-service API keys:** enable `ApiKeyConfig` on the plugin or assemble `ApiKeyTransport` + `ApiKeyStrategy` manually; see [API keys](../guides/api_keys.md) and [Backends configuration](../configuration/backends.md#api-key-backend).

See also [Request lifecycle](request_lifecycle.md).
