### Install OAuth extras

Source: https://zylvext.github.io/litestar-auth/how-to/oauth

Install the necessary dependencies for OAuth support using uv.

```bash
uv add 'litestar-auth[oauth]'
```

--------------------------------

### Run live FAPI-to-DPoP example with docker/reference/fapi/verify.sh

Source: https://zylvext.github.io/litestar-auth/merchant/authorization-details

Run the live FAPI-to-DPoP example with this shell command. The exact schema is payment authorization details v1.

```sh
sh docker/reference/fapi/verify.sh

```

--------------------------------

### Set up and verify the development environment

Source: https://zylvext.github.io/litestar-auth/contributing

Run these commands after installing the locked development environment. `just check` includes Ruff, ty, import-linter, documentation version-lock validation, dependency pin validation, and protocol vectors.

```shell
just setup
just check
uv run deptry .
just test
just docs-build

```

--------------------------------

### Install litestar-auth and aiosqlite with uv

Source: https://zylvext.github.io/litestar-auth/quickstart

Adds the litestar-auth package and the aiosqlite driver as project dependencies. Run this before configuring the database-backed cookie session preset.

```shell
uv add litestar-auth aiosqlite

```

--------------------------------

### Install litestar-auth and AuthWeave packages

Source: https://zylvext.github.io/litestar-auth/install

Use uv to add the core litestar-auth and AuthWeave packages to your project.

```bash
uv add litestar-auth
uv add authweave-core
uv add authweave-workload
uv add authweave-otel
uv add authweave-webhooks
uv add authweave-http-signatures
```

--------------------------------

### Payment authorization details v1 JSON example

Source: https://zylvext.github.io/litestar-auth/schemas/payment-authorization-v1

This is the exact JSON object defined by the RFC 9396 profile. It shows the required fields: type, actions, locations, instructedAmount, and an optional identifier. The example uses EUR currency and an amount of 100.00.

```json
{
  "type": "https://zylvext.github.io/litestar-auth/schemas/payment-authorization-v1",
  "actions": ["initiate"],
  "locations": ["https://api.example/v1/payments"],
  "instructedAmount": {"currency": "EUR", "amount": "100.00"},
  "identifier": "payment-123"
}
```

--------------------------------

### InMemoryReplayStore.__init__

Source: https://zylvext.github.io/litestar-auth/api/authweave-core

Initializes an InMemoryReplayStore with a bounded capacity and an injectable monotonic clock. Raises ValueError if the capacity is not positive.

```APIDOC
## InMemoryReplayStore.__init__

### Description
Initializes an InMemoryReplayStore with a bounded capacity and an injectable monotonic clock.

### Method
__init__(*, capacity, time_source)

### Parameters
- **capacity** (int) - Required - Maximum number of entries the store can hold.
- **time_source** (callable) - Required - A monotonic clock function used for TTL calculations.

### Raises
- **ValueError** - If the capacity is not positive.

```

--------------------------------

### ambient_trace_correlation()

Source: https://zylvext.github.io/litestar-auth/api/authweave-core

Returns the trace correlation installed by the innermost active security observation. Returns None when telemetry is disabled.

```APIDOC
## ambient_trace_correlation()

### Description
Return correlation installed by the innermost active security observation.

### Returns
- **TraceCorrelation | None** - Current correlation, or None when telemetry is disabled.
```

--------------------------------

### LitestarAuth.__init__

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Constructor for the LitestarAuth plugin.

```APIDOC
## `LitestarAuth.__init__(config)`

### Description
Store the plugin configuration and validate the requested setup.

### Method
N/A

### Endpoint
N/A

### Parameters
- **config** (`LitestarAuthConfig[UP, ID]`) - Required - Fully specified plugin configuration (session factory, backends, user manager factory, optional OAuth/TOTP settings).

### Request Example
N/A

### Response
N/A

```

--------------------------------

### Verify release artifacts and provenance script

Source: https://zylvext.github.io/litestar-auth/releasing

A Bash script that verifies artifact integrity by comparing GitHub release assets with PyPI files and checking attestations. It requires gh, curl, jq, sha256sum, and uv to be installed.

```bash
set -euo pipefail
VERSION=7.1.2
REPOSITORY=ZYLVEXT/litestar-auth
TAG_SHA=$(gh api "repos/$REPOSITORY/git/ref/tags/$VERSION" --jq .object.sha)
verification_dir=$(mktemp -d)
trap 'rm -rf "$verification_dir"' EXIT
mkdir -p "$verification_dir/github" "$verification_dir/pypi"

attestation_policy=(
  --repo "$REPOSITORY"
  --signer-workflow "$REPOSITORY/.github/workflows/3_release.yml"
  --signer-digest "$TAG_SHA"
  --source-ref "refs/tags/$VERSION"
  --source-digest "$TAG_SHA"
  --deny-self-hosted-runners
)

gh release verify "$VERSION" --repo "$REPOSITORY"
gh release download "$VERSION" --repo "$REPOSITORY" --dir "$verification_dir/github"
gh release view "$VERSION" --repo "$REPOSITORY" --json assets \
  --jq '.assets[] | "\(.digest | sub("^sha256:"; ""))  \(.name)"' \
  > "$verification_dir/SHA256SUMS"
(cd "$verification_dir/github" && sha256sum --check "$verification_dir/SHA256SUMS")
for asset in "$verification_dir/github"/*; do
  gh release verify-asset "$VERSION" "$asset" --repo "$REPOSITORY"
done

publishers=(
  authweave-core:pypi-core
  litestar-auth:pypi
  authweave-workload:pypi-workload
  authweave-otel:pypi-otel
  authweave-webhooks:pypi-webhooks
  authweave-http-signatures:pypi-http-signatures
)
for publisher in "${publishers[@]}"; do
  project=${publisher%%:*}
  environment=${publisher#*:}
  jq -e --arg project "$project" --arg version "$VERSION" '
    .bomFormat == "CycloneDX" and
    .specVersion == "1.7" and
    .metadata.component.name == $project and
    .metadata.component.version == $version
  ' "$verification_dir/github/$project-$VERSION.cdx.json" >/dev/null
  while IFS= read -r url; do
    filename=${url##*/}
    curl -fsSL "$url" -o "$verification_dir/pypi/$filename"
    cmp "$verification_dir/github/$filename" "$verification_dir/pypi/$filename"
    gh attestation verify "$verification_dir/github/$filename" "${attestation_policy[@]}"
    sbom_attestations=$(gh attestation verify \
      "$verification_dir/github/$filename" \
      "${attestation_policy[@]}" \
      --predicate-type https://cyclonedx.org/bom \
      --format json)
    jq -cS '.[].verificationResult.statement.predicate' <<< "$sbom_attestations" \
      | sort -u > "$verification_dir/signed.cdx.json"
    test "$(wc -l < "$verification_dir/signed.cdx.json")" -eq 1
    test "$(jq -cS . "$verification_dir/github/$project-$VERSION.cdx.json")" \
      = "$(cat "$verification_dir/signed.cdx.json")"
    uvx --from pypi-attestations pypi-attestations verify pypi \
      --repository "https://github.com/$REPOSITORY" "$url"
    curl -fsSL \
      "https://pypi.org/integrity/$project/$VERSION/$filename/provenance" \
      | jq -e --arg environment "$environment" '
          .attestation_bundles | length > 0 and all(.[].publisher;
            .kind == "GitHub" and
            .repository == "ZYLVEXT/litestar-auth" and
            .workflow == "3_release.yml" and
            .environment == $environment)
        ' >/dev/null
  done < <(curl -fsSL "https://pypi.org/pypi/$project/$VERSION/json" | jq -r '.urls[].url')
done
```

--------------------------------

### WorkloadLifecycleService.__init__

Source: https://zylvext.github.io/litestar-auth/api/authweave-workload

Constructor that binds persistence and bounded lifecycle policy.

```APIDOC
## WorkloadLifecycleService.__init__

### Description
Bind persistence and bounded lifecycle policy.

### Method
Constructor

### Signature
`__init__(store, *, issuer, actor, correlation_id, event_recorder, active_credential_limit=4, maximum_rotation_lead=timedelta(days=7))`

### Parameters
- **store** - The persistence store.
- **issuer** - The issuer identifier.
- **actor** - The actor identifier.
- **correlation_id** - The correlation identifier.
- **event_recorder** - The event recorder instance.
- **active_credential_limit** (int, optional) - Maximum number of active credentials. Defaults to 4.
- **maximum_rotation_lead** (timedelta, optional) - Maximum rotation lead time. Defaults to 7 days.

### Raises
- **ValueError** - If the call cannot complete.

```

--------------------------------

### Run preflight verification gates

Source: https://zylvext.github.io/litestar-auth/releasing

Execute these commands to verify the workspace state, build artifacts, and run tests before initiating a release.

```bash
just setup
just check
just deptry-check
just test
just docs-build
just build
```

--------------------------------

### BaseUserManager.__init__

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Initialize the user manager with either a persistence backend or a configuration object.

```APIDOC
## `BaseUserManager.__init__`

### Description
Initialize the user manager with either a persistence backend or a configuration object.

### Method
Constructor

### Signature
```
__init__(*, config: BaseUserManagerConfig[UP, ID]) -> None
```
```
__init__(user_db: BaseUserStore[UP, ID], **options: Unpack[BaseUserManagerConstructorKwargs[UP, ID]]) -> None
```
```
__init__(*, user_db: BaseUserStore[UP, ID], **options: Unpack[BaseUserManagerConstructorKwargs[UP, ID]]) -> None
```

### Parameters
- **user_db** (`BaseUserStore[UP, ID] | None`) - Optional - Persistence backend used to load and update users.
- **config** (`BaseUserManagerConfig[UP, ID] | None`) - Optional - User-manager configuration object. Do not combine with `user_db` or keyword options.
- **options** (`Unpack[BaseUserManagerConstructorKwargs[UP, ID]]`) - Optional - Individual user-manager settings. Do not combine with `config`.

### Raises
- `TypeError` - If neither `user_db` nor `config` is provided.
- `ValueError` - If `config` is combined with `user_db` or keyword options.

```

--------------------------------

### BaseUserManager __init__ overloads

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Three constructor overloads: one with config only, one with user_db and keyword options, and one with keyword-only user_db and options. The config and user_db approaches are mutually exclusive; combining them raises ValueError.

```python
__init__(*, config: BaseUserManagerConfig[UP, ID]) -> None

```

```python
__init__(user_db: BaseUserStore[UP, ID], **options: Unpack[BaseUserManagerConstructorKwargs[UP, ID]]) -> None

```

```python
__init__(*, user_db: BaseUserStore[UP, ID], **options: Unpack[BaseUserManagerConstructorKwargs[UP, ID]]) -> None

```

--------------------------------

### LitestarAuth.on_cli_init

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Lifecycle hook to register CLI commands.

```APIDOC
## `LitestarAuth.on_cli_init(cli)`

### Description
Register plugin-owned CLI commands without affecting app startup wiring.

### Method
N/A

### Endpoint
N/A

### Parameters
- **cli** (unknown) - Required - The CLI object.

### Request Example
N/A

### Response
N/A

```

--------------------------------

### AuthenticationCoordinator.__init__(providers)

Source: https://zylvext.github.io/litestar-auth/api/authweave-core

Constructor for the authentication coordinator. Validates the provider inventory.

```APIDOC
## AuthenticationCoordinator.__init__(providers)

### Description
Freeze and validate the provider inventory.

### Method
__init__

### Parameters
- **providers** (list) - Required - The list of authentication providers.

### Raises
- **ValueError** - If provider names or profiles are invalid or duplicated.

### Returns
None
```

--------------------------------

### WorkloadLifecycleService.list_applications

Source: https://zylvext.github.io/litestar-auth/api/authweave-workload

Returns a bounded deterministic application inventory page.

```APIDOC
## WorkloadLifecycleService.list_applications

### Description
Return a bounded deterministic application inventory page.

### Method
async

### Signature
`async list_applications(*, offset=0, limit=50, owner_ref=None, environment=None, status=None)`

### Parameters
- **offset** (int, optional) - The offset for pagination. Defaults to 0.
- **limit** (int, optional) - The maximum number of items to return. Defaults to 50.
- **owner_ref** (optional) - Filter by owner reference.
- **environment** (optional) - Filter by environment.
- **status** (optional) - Filter by status.

### Returns
- A bounded deterministic application inventory page.

```

--------------------------------

### LitestarAuth.on_app_init

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Lifecycle hook to register auth components on the app.

```APIDOC
## `LitestarAuth.on_app_init(app_config)`

### Description
Register auth middleware, controllers, and dependencies on the app.

### Method
N/A

### Endpoint
N/A

### Parameters
- **app_config** (unknown) - Required - The application configuration.

### Request Example
N/A

### Response
- **AppConfig** - The updated application config.

```

--------------------------------

### CookieTransport.__init__(config=None, **options)

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Initializes the cookie transport configuration.

```APIDOC
## `CookieTransport.__init__(config=None, **options)`

### Description
Initialize the cookie transport configuration.

### Parameters
- **config** (`CookieTransportConfig | None`) - Optional - Cookie transport configuration. Omit for secure defaults. Defaults to `None`.
- **options** (`Unpack[CookieTransportConfigOptions]`) - Optional - Individual cookie transport settings. Do not combine with `config`. Defaults to `{}`.

### Raises
- **ValueError** - If `config` and keyword options are combined.
- **ValueError** - If `samesite="none"` is configured with `secure=False`.
```

--------------------------------

### Verify webhook packs with Python

Source: https://zylvext.github.io/litestar-auth/merchant/environment-packs/webhooks

Use this command to validate the environment pack configurations using the provided verification script.

```bash
uv run python docs/merchant/environment-packs/webhooks/verify_packs.py
```

--------------------------------

### Verify a package distribution with uv, ruff, ty, and pytest

Source: https://zylvext.github.io/litestar-auth/contributing

Run these commands from the changed package directory to verify a distribution. Replace `<distribution>` and `<import_package>` with the package's distribution and import-package names. The five values are `authweave-core`/`authweave_core`, `authweave-workload`/`authweave_workload`, `authweave-otel`/`authweave_otel`, `authweave-webhooks`/`authweave_webhooks`, and `authweave-http-signatures`/`authweave_http_signatures`.

```shell
uv sync --frozen --all-packages --all-extras --group dev
uv run --no-sync python -c "import pathlib, sysconfig; p = pathlib.Path(sysconfig.get_paths()['purelib']) / 'coverage_subprocess.pth'; p.write_text('import coverage; coverage.process_startup()\n')"
cd packages/<distribution>
uv run --no-sync ruff check .
uv run --no-sync ruff format --check --preview .
uv run --no-sync ty check <import_package> tests
COVERAGE_PROCESS_START=pyproject.toml uv run --no-sync pytest \
  --cov=<import_package> --cov-branch --cov-fail-under=100

```

--------------------------------

### Configure DatabaseTokenAuthConfig with LitestarAuth

Source: https://zylvext.github.io/litestar-auth/quickstart

Configures the database-backed cookie session preset. Requires the application's normal database and account-lifecycle objects (session_maker, User, UserManager, user_db_factory, user_manager_security). The minimal configuration warns that default rate-limit and account-token replay state is process-local; use worker-shared backends for multi-worker production.

```python
from litestar import Litestar
from litestar_auth import DatabaseTokenAuthConfig, LitestarAuth, LitestarAuthConfig

config = LitestarAuthConfig(
    database_token_auth=DatabaseTokenAuthConfig(
        token_hash_secret=session_digest_secret,
    ),
    csrf_secret=csrf_secret,
    session_maker=session_maker,
    user_model=User,
    user_manager_class=UserManager,
    user_db_factory=user_db_factory,
    user_manager_security=user_manager_security,
)

app = Litestar(plugins=[LitestarAuth(config)])

```

--------------------------------

### create_session_devices_controller overload signatures

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Two overload signatures for the session-devices controller factory. Use the first when passing a SessionDevicesControllerConfig; use the second when passing individual options. Raises TypeError if both config and keyword options are supplied.

```python
create_session_devices_controller(config: SessionDevicesControllerConfig[UP, ID]) -> type[Controller]
```

```python
create_session_devices_controller(**options: Unpack[SessionDevicesControllerOptions[UP, ID]]) -> type[Controller]
```

--------------------------------

### WorkloadLifecycleService.create_application

Source: https://zylvext.github.io/litestar-auth/api/authweave-workload

Creates an enabled service application.

```APIDOC
## WorkloadLifecycleService.create_application

### Description
Create an enabled service application.

### Method
async

### Signature
`async create_application(*, application_id, environment, owner_ref, metadata=_EMPTY_METADATA)`

### Parameters
- **application_id** - The application identifier.
- **environment** - The environment for the application.
- **owner_ref** - The owner reference.
- **metadata** (optional) - Metadata for the application. Defaults to empty.

### Returns
- **tuple[ServiceApplication, SecurityEvent]** - The created application.

```

--------------------------------

### PrincipalRef.__post_init__

Source: https://zylvext.github.io/litestar-auth/api/authweave-core

Validates bounded identity components after initialization.

```APIDOC
## PrincipalRef.__post_init__

### Description
Validates bounded identity components after initialization.

### Method
__post_init__()

```

--------------------------------

### Run direct mTLS DPoP live harness

Source: https://zylvext.github.io/litestar-auth/merchant/dpop

Runs the direct mTLS live harness for DPoP verification.

```shell
sh docker/reference/verify.sh
```

--------------------------------

### Run Standard Webhooks vector manifest (Python and Node.js)

Source: https://zylvext.github.io/litestar-auth/merchant/webhooks

Run the language-neutral vector manifest for Standard Webhooks v1a. Both commands consume the same signed bytes, active/next/retiring overlap, and negative cases. The Node.js verifier uses only the independent built-in Ed25519 implementation.

```bash
uv run --package authweave-webhooks python docs/vectors/webhooks/v1a/verify_vectors.py
```

```bash
node docs/vectors/webhooks/v1a/verify_vectors.mjs
```

--------------------------------

### AuthenticationBackend.login

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Issues a token through the configured strategy and transport.

```APIDOC
## AuthenticationBackend.login

### Description
Issues a token through the configured strategy and transport.

### Method
async

### Signature
`login(user, *, session_id=None)`

### Parameters
- **user** (object) - Required - The user to authenticate.
- **session_id** (optional) - Optional - Session identifier for session binding.

### Returns
- **Response[Any]** - Response mutated by the configured transport for login.

### Raises
- **TypeError** - If session binding is requested for an unsupported strategy.

```

--------------------------------

### ReplayStore.check_and_store(key, *, ttl_seconds)

Source: https://zylvext.github.io/litestar-auth/api/authweave-core

Asynchronously records a key if absent and reports whether it was already present. Returns a ReplayOutcome indicating the result of the atomic put-if-absent operation.

```APIDOC
## ReplayStore.check_and_store(key, *, ttl_seconds)

### Description
Asynchronously records a key if absent and reports whether it was already present. Returns a ReplayOutcome indicating the result of the atomic put-if-absent operation.

### Method
check_and_store

### Parameters
- **key** (unknown) - Required - The key to record.
- **ttl_seconds** (unknown) - Required - Time-to-live for the key in seconds.

### Returns
- **ReplayOutcome** - The typed put-if-absent outcome.
```

--------------------------------

### BaseUserManager.create

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Create a new user with password hashing and field validation.

```APIDOC
## `BaseUserManager.create`

### Description
Create a new user, hashing the provided password before persistence. With `safe=True` (default), any field outside the manager's `creatable_fields` allowlist is dropped. With `safe=False`, undeclared fields are rejected. Privileged fields (`is_active`, `is_verified`, `roles`) are silently dropped unless `allow_privileged=True`.

### Method
async

### Signature
```
create(user_create: UserCreate, *, safe: bool = True, allow_privileged: bool = False) -> UP
```

### Parameters
- **user_create** (`UserCreate`) - Required - The user creation data.
- **safe** (`bool`) - Optional - If `True`, drop fields outside the allowlist; if `False`, reject undeclared fields.
- **allow_privileged** (`bool`) - Optional - If `True`, allow privileged fields.

### Returns
- **UP** - The newly created user.

```

--------------------------------

### Configure LitestarAuth with DatabaseTokenAuthConfig

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Wire the database-backed cookie-session preset when building a Litestar application. Requires environment variables for token hash, CSRF, reset password, and verification secrets. The user manager class and session maker must be provided.

```python
import os
from uuid import UUID

from litestar import Litestar
from litestar_auth import DatabaseTokenAuthConfig, LitestarAuth, LitestarAuthConfig, UserManagerSecurity
from litestar_auth.models import User

database_token_hash_secret = os.environ["LITESTAR_AUTH_DATABASE_TOKEN_HASH_SECRET"]
csrf_secret = os.environ["LITESTAR_AUTH_CSRF_SECRET"]
reset_password_token_secret = os.environ["LITESTAR_AUTH_RESET_PASSWORD_TOKEN_SECRET"]
verify_token_secret = os.environ["LITESTAR_AUTH_VERIFY_TOKEN_SECRET"]

config = LitestarAuthConfig[User, UUID](
    database_token_auth=DatabaseTokenAuthConfig(
        token_hash_secret=database_token_hash_secret,
    ),
    csrf_secret=csrf_secret,
    user_model=User,
    user_manager_class=YourUserManager,
    session_maker=session_maker,  # e.g. async_sessionmaker(...)
    user_manager_security=UserManagerSecurity(
        verification_token_secret=verify_token_secret,
        reset_password_token_secret=reset_password_token_secret,
    ),
)
app = Litestar(plugins=[LitestarAuth(config)])
```

--------------------------------

### AuthenticationBackend.with_session

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Returns a backend whose strategy is rebound to the provided session when supported.

```APIDOC
## AuthenticationBackend.with_session

### Description
Returns a backend whose strategy is rebound to the provided session when supported.

### Method
sync

### Signature
`with_session(session)`

### Parameters
- **session** (object) - Required - The session to bind to the strategy.

### Returns
- **AuthenticationBackend** - A new backend instance with the rebound strategy.

```

--------------------------------

### Verify payment-v1 vectors

Source: https://zylvext.github.io/litestar-auth/merchant/http-signatures

Commands to run vector verification scripts for the payment-v1 profile using Python and Node.js.

```bash
uv run --package authweave-http-signatures python docs/vectors/http-signatures/payment-v1/verify_vectors.py
node docs/vectors/http-signatures/payment-v1/verify_vectors.mjs
```

--------------------------------

### Run Docker Redis and live HTTP DPoP smoke test

Source: https://zylvext.github.io/litestar-auth/merchant/dpop

Runs a Docker Redis and live HTTP resource-server smoke test without a client certificate. Uses the application-owned EXTERNAL_TARGET.

```shell
sh docker/reference/dpop/verify.sh
```

--------------------------------

### ServiceApplication.__post_init__()

Source: https://zylvext.github.io/litestar-auth/api/authweave-workload

Validates stable public fields of a service application. Raises ValueError if the call cannot complete.

```APIDOC
## ServiceApplication.__post_init__()

### Description
Validate stable public fields.

### Method
__post_init__

### Parameters
None

### Returns
None

### Raises
- **ValueError** - If the call cannot complete.

```

--------------------------------

### create_users_controller overload signatures

Source: https://zylvext.github.io/litestar-auth/api/litestar-auth

Two overload signatures for the users controller factory. Use the first when passing a UsersControllerConfig; use the second when passing individual options. Raises ValueError if config and keyword options are combined.

```python
create_users_controller(*, config: UsersControllerConfig[ID]) -> type[Controller]
```

```python
create_users_controller(**options: Unpack[UsersControllerOptions[ID]]) -> type[Controller]
```