> ## 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.credentials

> 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 |
| - | - |
| [`Credential`](#credential) | Class |
| [`CredentialContext`](#credentialcontext) | Class |
| [`CredentialError`](#credentialerror) | Class |
| [`CredentialProvider`](#credentialprovider) | Class |
| [`CredentialProviderError`](#credentialprovidererror) | Class |
| [`CredentialRequest`](#credentialrequest) | Class |
| [`CredentialUnavailableError`](#credentialunavailableerror) | Class |
| [`credentials`](#credentials) | Namespace |

## Credential

Opaque material Harnest passes transiently and never serializes.

Material may be a token or a framework-native credential value. Harnest
keeps either form redacted and requires transport adapters to reveal it at
the final outbound security boundary.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

> [accordion] Example
>
> ```python theme={null}
> from harnest.credentials import Credential
>
> credential: Credential  # returned by Harnest, not constructed directly
> ```

### Credential.reveal

```python theme={null}
Credential.reveal() -> Any
```

Return credential material for transport adapters at the security boundary.

> [accordion] Example
>
> ```python theme={null}
> from harnest.credentials import Credential
>
> credential: Credential
> result = credential.reveal()
> ```

## CredentialContext

Private invocation capability for resolving outbound credentials.

The context deliberately exposes no provider, principal, or resource-map
access.  Keeping this as a dedicated type lets stage contexts share the
invocation lifetime without making credential authority enumerable.

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

> [accordion] Example
>
> ```python theme={null}
> from harnest.credentials import CredentialContext
>
> context = CredentialContext()
> ```

### CredentialContext.resolve

```python theme={null}
async CredentialContext.resolve(audience: str, scopes: Iterable[str] = ()) -> Credential
```

Resolve opaque material using only private invocation identity.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `audience` | `str` | Required |
> | `scopes` | `Iterable[str]` | `()` |
>
> ```python theme={null}
> from harnest.credentials import CredentialContext
>
> context: CredentialContext
> credential = await context.resolve(audience=...)
> ```

## CredentialError

Base class for safe credential-resolution failures.

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

## CredentialProvider

Application-owned source of short-lived invocation credentials.

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

> [accordion] Example
>
> ```python theme={null}
> from harnest.credentials import CredentialProvider
>
> class MyCredentialProvider(CredentialProvider):
>     ...
> ```

### CredentialProvider.start

```python theme={null}
async CredentialProvider.start() -> None
```

Initialize provider-owned clients before accepting invocations.

> [accordion] Example
>
> ```python theme={null}
> from harnest.credentials import CredentialProvider
>
> provider: CredentialProvider
> await provider.start()
> ```

### CredentialProvider.resolve

```python theme={null}
async CredentialProvider.resolve(request: CredentialRequest) -> Credential | None
```

Resolve a credential for one invocation and downstream audience.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request` | `CredentialRequest` | Required |
>
> ```python theme={null}
> from harnest.credentials import CredentialProvider
>
> provider: CredentialProvider
> credential = await provider.resolve(request=...)
> ```

### CredentialProvider.close

```python theme={null}
async CredentialProvider.close() -> None
```

Release provider-owned clients after invocations have drained.

> [accordion] Example
>
> ```python theme={null}
> from harnest.credentials import CredentialProvider
>
> provider: CredentialProvider
> await provider.close()
> ```

## CredentialProviderError

Raised when a configured provider fails or violates its contract.

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

## CredentialRequest

Authenticated principal and authorization scope for one resolution.

```python theme={null}
CredentialRequest(
    audience: str,
    scopes: tuple[str, ...],
    framework: str,
    agent_name: str,
    invocation_id: str,
    session_id: str,
    principal: AuthPrincipal,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `audience` | `str` | `—` |
| `scopes` | `tuple[str, ...]` | `—` |
| `framework` | `str` | `—` |
| `agent_name` | `str` | `—` |
| `invocation_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `principal` | `AuthPrincipal` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `audience` | `str` | Required |
> | `scopes` | `tuple[str, ...]` | Required |
> | `framework` | `str` | Required |
> | `agent_name` | `str` | Required |
> | `invocation_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `principal` | `AuthPrincipal` | Required |
>
> ```python theme={null}
> from harnest.credentials import CredentialRequest
>
> request = CredentialRequest(
>     audience=...,
>     scopes=...,
>     framework=...,
>     agent_name=...,
>     invocation_id=...,
>     session_id=...,
>     principal=...,
> )
> ```

## CredentialUnavailableError

Raised when an invocation cannot obtain a requested credential.

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

## credentials

Private invocation capability for resolving outbound credentials.

The context deliberately exposes no provider, principal, or resource-map
access.  Keeping this as a dedicated type lets stage contexts share the
invocation lifetime without making credential authority enumerable.

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

### credentials.resolve

```python theme={null}
async credentials.resolve(audience: str, scopes: Iterable[str] = ()) -> Credential
```

Resolve opaque material using only private invocation identity.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `audience` | `str` | Required |
> | `scopes` | `Iterable[str]` | `()` |
>
> ```python theme={null}
> from harnest.credentials import credentials
>
> credential = await credentials.resolve(audience=...)
> ```


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