mirror of
https://github.com/agentrhq/authsome.git
synced 2026-09-19 01:34:19 +08:00
Manoj Bajaj
0a5126cc0f
Keep v0.7 Mintlify refresh while adopting onboard/init renames and onboard flow updates from main. Co-authored-by: Cursor <cursoragent@cursor.com>
135 lines
4.6 KiB
Plaintext
135 lines
4.6 KiB
Plaintext
---
|
|
title: "Python library"
|
|
sidebarTitle: "Python library"
|
|
description: "Use authsome from Python via the CLI, proxy, export, or daemon HTTP API."
|
|
icon: "code"
|
|
keywords: ["authsome python", "authsome library", "authsome programmatic", "authsome daemon 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
|
|
pip install authsome
|
|
# or
|
|
uv pip install authsome
|
|
```
|
|
|
|
Python 3.13 or newer.
|
|
|
|
## Quick start (proxy)
|
|
|
|
```bash
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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>
|