Metadata-Version: 2.4
Name: authsome
Version: 0.2.3rc71
Summary: A portable local authentication library for AI agents and developer tools
Author-email: Manoj Bajaj <manojbajaj95@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,api-key,auth,credentials,mcp,oauth2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Requires-Dist: click>=8.0
Requires-Dist: cryptography>=41.0
Requires-Dist: fastapi>=0.115
Requires-Dist: jinja2>=3.1
Requires-Dist: keyring>=24.0
Requires-Dist: loguru>=0.7
Requires-Dist: mitmproxy>=11.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.27
Requires-Dist: requests>=2.28
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Description-Content-Type: text/markdown

# authsome

[![PyPI version](https://img.shields.io/pypi/v/authsome.svg)](https://pypi.org/project/authsome/)
[![Python 3.13+](https://img.shields.io/pypi/pyversions/authsome.svg)](https://pypi.org/project/authsome/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI downloads](https://img.shields.io/pypi/dm/authsome.svg)](https://pypi.org/project/authsome/)
[![Tests](https://github.com/manojbajaj95/authsome/actions/workflows/test.yml/badge.svg)](https://github.com/manojbajaj95/authsome/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/manojbajaj95/authsome/branch/main/graph/badge.svg)](https://codecov.io/gh/manojbajaj95/authsome)

```text
               __  __
  ____ ___  __/ /_/ /_  _________  ____ ___  ___
 / __ `/ / / / __/ __ \/ ___/ __ \/ __ `__ \/ _ \
/ /_/ / /_/ / /_/ / / (__  ) /_/ / / / / / /  __/
\__,_/\__,_/\__/_/ /_/____/\____/_/ /_/ /_/\___/
```

**Local-first credential broker and vault for AI Agents**

An open-source credential broker that sits between your agents and the services they call. Instead of sharing credentials with every agent, log in once via OAuth2 or API keys. Authsome stores credentials securely and injects them via an HTTP proxy. You get one place to manage access, rotate keys, and see what every agent is doing.

---

## Demo

https://github.com/user-attachments/assets/27f9b229-baf4-4889-be9a-378a133654dc

---

## Why Agents need Authsome

Agents run beyond interactive sessions. They live in CI, over SSH, in cron jobs, in background workers, and in parallel pipelines. They need API access that survives without a human in the loop.

Hardcoded environment tokens leak or go stale, and building auth flow logic, token storage, refresh handling, and per-provider config into every project rebuilds the same plumbing every time.

Authsome is the local credential layer agents call at runtime.

- **No credential sprawl.** One encrypted store — every provider, every agent, one place.
- **No SaaS, no privacy trade-off.** Credentials never leave your machine. Eliminates credential exfiltration risks as agents never see them.
- **No browser required at runtime.** Setup can use browser PKCE, device code, or a browser bridge for secure API key entry. After that, agents run headlessly.

---

## How It Works

The CLI is the agent's interface: setup once, then inject fresh credentials whenever a tool runs.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/authsome-how-it-works-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="assets/authsome-how-it-works-light.svg">
  <img alt="Authsome Architecture" src="assets/authsome-how-it-works-light.svg" width="100%">
</picture>

Authenticate once:

```bash
uvx authsome login github
```

Then agents get valid credentials on demand:

```bash
uvx authsome get github --field access_token --show-secret
# → ghu_...

export $(uvx authsome export github)
# → sets GITHUB_ACCESS_TOKEN in current shell

uvx authsome run python my_agent.py
# runs behind a local auth proxy that injects headers at request time
# without exposing secrets in the child process environment.
# matched automatically via provider host_url (e.g. api.openai.com)
```

Credentials are stored locally, encrypted at rest, and refreshed before expiry. No server. No account. No cloud.

---

## Why Authsome

| | authsome | Hardcoded env tokens | DIY |
|--|:--------:|:--------------------:|:---:|
| Automatic token refresh | ✅ | ❌ | build it |
| OAuth2 + API keys | ✅ | ❌ | build it |
| Runtime headless use | ✅ | ✅ | varies |
| Local — no SaaS dependency | ✅ | ✅ | ✅ |
| Built-in providers, zero config | ✅ | ❌ | ❌ |
| Multi-account per provider | ✅ | ❌ | build it |

Authsome gives agents one command for a valid token, without scattering long-lived secrets across every project.

---

## Quick Start

```bash
uvx authsome login github                  # opens browser, completes PKCE flow
uvx authsome login github --flow device_code  # headless: Device Code, works over SSH and CI
uvx authsome login openai                  # secure API key entry via browser bridge
uvx authsome list                          # all connections + token status
```

## Docs

The full documentation site lives in [`docs/site/`](docs/site/)

- [Quickstart](docs/site/quickstart.mdx)
- [CLI reference](docs/site/reference/cli.mdx)
- [Architecture](docs/site/concepts/architecture.mdx)
- [Custom providers](docs/site/guides/custom-providers.mdx)
- [Troubleshooting](docs/site/troubleshooting/doctor.mdx)

To preview locally:

```bash
cd docs/site
npm i -g mint   # requires Node.js >= 20.17.0
mint dev
```



## Specs

- [Authsome v1](docs/specs/authsome-v1.md)

## License

MIT — see [LICENSE](LICENSE).
