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

# Python library

> Use authsome from Python via the CLI, proxy, export, or daemon HTTP API.

Authsome ships as a Python package, but the supported integration surface for agents is **not** an in-process credential API. Use one of these paths instead:

1. **`authsome run -- <command>`** — recommended. The proxy injects credentials without exposing secrets to the child process.
2. **`authsome export <provider> --format env`** — when the tool cannot route through an HTTP proxy.
3. **Daemon HTTP API** — when you are building tooling that talks to the local daemon over PoP-authenticated HTTP.

<Note>
  The CLI plus proxy covers almost every workflow. Drop to export or the HTTP API only when embedding authsome in custom orchestration or non-Python runtimes. See [Run agents with the proxy](/guides/run-agents-with-proxy).
</Note>

## Install

```bash theme={null}
pip install authsome
# or
uv pip install authsome
```

Python 3.13 or newer.

## Quick start (proxy)

```bash theme={null}
authsome onboard
authsome login github
authsome run -- python my_script.py
```

Your script reads placeholder env vars; the proxy substitutes real credentials on outbound HTTP requests. No authsome import required in the script.

## Quick start (export)

```bash theme={null}
eval "$(authsome export github --format env)"
python -c 'import os; print(os.environ["GITHUB_ACCESS_TOKEN"][:8] + "...")'
```

Refresh is handled by the daemon. Re-run export when you need fresh values in a long-lived shell.

## Quick start (daemon HTTP API)

The CLI and proxy both call the daemon at `http://127.0.0.1:7998/api/...` with PoP JWT authentication. Every protected request carries `Authorization: PoP <jwt>` signed by the local Ed25519 identity key.

```bash theme={null}
curl -s http://127.0.0.1:7998/api/health | jq
curl -s http://127.0.0.1:7998/api/connections | jq
```

See [HTTP daemon API](/reference/daemon-api) for every route. For programmatic PoP signing, follow `src/authsome/cli/client.py` in the repository — that client is the reference implementation.

## Public package exports

The top-level `authsome` package re-exports models, errors, and the `Vault` interface for tests and advanced embedding:

```python theme={null}
from authsome import (
    Vault,
    AuthType,
    ConnectionRecord,
    ConnectionStatus,
    ExportFormat,
    FlowType,
    ProviderDefinition,
    ProviderType,
    Sensitive,
    AuthsomeError,
    AuthenticationFailedError,
    ConnectionNotFoundError,
    CredentialMissingError,
    IdentityNotFoundError,
    ProviderNotFoundError,
    RefreshFailedError,
    TokenExpiredError,
)
```

`CredentialService` (the daemon's credential lifecycle coordinator) lives in `authsome.server` and is constructed by the daemon's dependency injection layer. It is not a supported public embedding API.

## Vault

A minimal encrypted key-value interface. Credential records are stored under keys like `vault:<vault_id>:<provider>:connection:<name>`. Direct vault access is rare outside tests:

```python theme={null}
vault.get(key)
vault.put(key, value)
vault.delete(key)
vault.list(prefix)
```

Prefer the CLI or daemon API; they manage encryption, refresh, and Principal/Vault authorization for you.

## Errors

All exceptions subclass `AuthsomeError`. Common ones:

| Exception                   | When                                            |
| --------------------------- | ----------------------------------------------- |
| `ProviderNotFoundError`     | Unknown provider name                           |
| `ConnectionNotFoundError`   | Requested connection doesn't exist              |
| `CredentialMissingError`    | Provider registered but no completed connection |
| `RefreshFailedError`        | Provider rejected the refresh token             |
| `TokenExpiredError`         | Token expired and refresh wasn't possible       |
| `AuthenticationFailedError` | Login flow failed or was cancelled              |
| `IdentityNotFoundError`     | Identity handle not registered with the daemon  |
| `StoreUnavailableError`     | Vault or store unreachable                      |

Exit codes in [CLI reference](/reference/cli) map one-to-one to these classes.

## When to use which surface

| Use the proxy                  | Use export                 | Use the HTTP API                  |
| ------------------------------ | -------------------------- | --------------------------------- |
| Python/Node/any HTTP agent     | SDKs that ignore proxies   | Custom tooling on top of authsome |
| Secrets must not appear in env | Short-lived shell sessions | Non-Python orchestrators          |
| Default for new integrations   | TLS-pinned SDKs            | Dashboards and automation         |

## What's next

<Columns cols={2}>
  <Card title="Architecture" icon="layer-group" href="/concepts/architecture">
    Identity, Vault, Principal, and the daemon.
  </Card>

  <Card title="HTTP daemon API" icon="server" href="/reference/daemon-api">
    Every route the daemon exposes.
  </Card>
</Columns>