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

# harnest.auth

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Exports

| Name | Kind |
| - | - |
| [`ANONYMOUS_USER_ID`](#anonymous_user_id) | Value or type alias |
| [`AnonymousAuthenticator`](#anonymousauthenticator) | Class |
| [`AuthPrincipal`](#authprincipal) | Class |
| [`AuthenticationError`](#authenticationerror) | Class |
| [`Authenticator`](#authenticator) | Class |
| [`ConnectionContext`](#connectioncontext) | Class |
| [`install_authentication`](#install_authentication) | Function |
| [`principal_for`](#principal_for) | Function |

## ANONYMOUS\_USER\_ID

```python theme={null}
ANONYMOUS_USER_ID = '_harnest_neutral'
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.auth import ANONYMOUS_USER_ID
> ```

## AnonymousAuthenticator

Development default that preserves the local single-user behavior.

```python theme={null}
AnonymousAuthenticator()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.auth import AnonymousAuthenticator
>
> authenticator = AnonymousAuthenticator()
> ```

### AnonymousAuthenticator.authenticate

```python theme={null}
async AnonymousAuthenticator.authenticate(connection: Any) -> AuthPrincipal
```

Return the built-in anonymous principal for every connection.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `connection` | `Any` | Required |
>
> ```python theme={null}
> from harnest.auth import AnonymousAuthenticator
>
> authenticator: AnonymousAuthenticator
> principal = await authenticator.authenticate(connection=...)
> ```

## AuthPrincipal

A verified tenant/user identity supplied by a deployment authenticator.

```python theme={null}
AuthPrincipal(
    user_id: str,
    claims: Mapping[str, Any] = ...,
    credentials: Mapping[str, Credential] = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `user_id` | `str` | `—` |
| `claims` | `Mapping[str, Any]` | `<lambda>()` |
| `credentials` | `Mapping[str, Credential]` | `<lambda>()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `claims` | `Mapping[str, Any]` | `...` |
> | `credentials` | `Mapping[str, Credential]` | `...` |
>
> ```python theme={null}
> from harnest.auth import AuthPrincipal
>
> principal = AuthPrincipal(user_id=...)
> ```

## AuthenticationError

A request did not satisfy the deployment authentication policy.

```python theme={null}
AuthenticationError(detail: str = 'Authentication required', *, status_code: int = 401) -> None
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.auth import AuthenticationError
>
> try:
>     ...
> except AuthenticationError as error:
>     ...
> ```

## Authenticator

Resolve one HTTP or WebSocket connection to a verified principal.

```python theme={null}
Authenticator(*args, **kwargs)
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.auth import Authenticator
>
> class MyAuthenticator(Authenticator):
>     ...
> ```

### Authenticator.authenticate

```python theme={null}
async Authenticator.authenticate(connection: Any) -> AuthPrincipal
```

Return the authenticated principal for one incoming connection.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `connection` | `Any` | Required |
>
> ```python theme={null}
> from harnest.auth import Authenticator
>
> authenticator: Authenticator
> principal = await authenticator.authenticate(connection=...)
> ```

## ConnectionContext

Framework-independent, read-only connection data for authentication.

```python theme={null}
ConnectionContext(
    transport: str,
    method: str | None,
    path: str,
    headers: Mapping[str, str],
    cookies: Mapping[str, str],
    query: Mapping[str, str],
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `transport` | `str` | `—` |
| `method` | `str \| None` | `—` |
| `path` | `str` | `—` |
| `headers` | `Mapping[str, str]` | `—` |
| `cookies` | `Mapping[str, str]` | `—` |
| `query` | `Mapping[str, str]` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `transport` | `str` | Required |
> | `method` | `str \| None` | Required |
> | `path` | `str` | Required |
> | `headers` | `Mapping[str, str]` | Required |
> | `cookies` | `Mapping[str, str]` | Required |
> | `query` | `Mapping[str, str]` | Required |
>
> ```python theme={null}
> from harnest.auth import ConnectionContext
>
> context = ConnectionContext(
>     transport=...,
>     method=...,
>     path=...,
>     headers=...,
>     cookies=...,
>     query=...,
> )
> ```

## install\_authentication

Protect execution/session routes while leaving discovery public.

```python theme={null}
install_authentication(app: Any, authenticator: Authenticator | None) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `app` | `Any` | Required |
> | `authenticator` | `Authenticator \| None` | Required |
>
> ```python theme={null}
> from harnest.auth import install_authentication
>
> install_authentication(app=..., authenticator=...)
> ```

## principal\_for

Read the principal installed before a protected route executes.

```python theme={null}
principal_for(connection: Any) -> AuthPrincipal
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `connection` | `Any` | Required |
>
> ```python theme={null}
> from harnest.auth import principal_for
>
> principal = principal_for(connection=...)
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.