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

# Introduction

> Credential broker for AI agents. Log in once via OAuth2 or API key. Authsome keeps the credentials fresh for every agent.

Authsome is a credential broker for AI agents. You authenticate once with a provider (GitHub, Google, OpenAI, Linear, and 41 other bundled services) and authsome keeps the credentials fresh for every agent run that follows.

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

## Why agents need this

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

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

Authsome acts as the credential broker agents call at runtime.

* **No credential sprawl.** One encrypted store, every provider, every agent, one place.
* **No SaaS dependency.** Self-host the daemon; credentials stay under your control.
* **No browser required at runtime.** You set up once using a browser or terminal prompt. After that, agents run headlessly.

## How it works

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

<Frame caption="Agents call authsome at runtime. The vault decrypts and returns a fresh token without exposing secrets to the agent.">
  ```mermaid theme={null}
  flowchart LR
      Agent -->|authsome| Vault["Local Vault<br/><i>(encrypted)</i>"]
      Vault -.->|fresh token / API key| Agent
  ```
</Frame>

Credentials are stored in an encrypted vault, refreshed before expiry, and injected into agents transparently through a proxy (`authsome run`).

## Start here

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install authsome, log in to your first provider, and run an agent in under 5 minutes.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command, every flag, every exit code.
  </Card>

  <Card title="Architecture" icon="layer-group" href="/concepts/architecture">
    The five layers (identity, policy, vault, auth, audit) and the proxy that ties them together.
  </Card>

  <Card title="Custom providers" icon="puzzle-piece" href="/guides/custom-providers">
    Add any OAuth2 or API-key service that authsome doesn't ship out of the box.
  </Card>
</Columns>

## Pick your path

<Columns cols={2}>
  <Card title="Log in with OAuth" icon="github" href="/guides/login-with-oauth">
    Browser-based PKCE flow for services like GitHub, Google, Linear.
  </Card>

  <Card title="Use API keys" icon="key" href="/guides/use-api-keys">
    Secure browser bridge for OpenAI, Anthropic, and similar providers.
  </Card>

  <Card title="Run agents with the proxy" icon="shield-halved" href="/guides/run-agents-with-proxy">
    Inject auth headers without exposing raw secrets to the child process.
  </Card>

  <Card title="Headless setup" icon="server" href="/guides/headless-device-code">
    Authenticate over SSH or in CI with the device code flow.
  </Card>
</Columns>

## Authsome compared

|                                 | authsome | Hardcoded env tokens |    DIY   |
| ------------------------------- | :------: | :------------------: | :------: |
| Automatic token refresh         |    Yes   |          No          | Build it |
| OAuth2 + API keys               |    Yes   |          No          | Build it |
| Runtime headless use            |    Yes   |          Yes         |  Varies  |
| Local, no SaaS dependency       |    Yes   |          Yes         |    Yes   |
| Built-in providers, zero config |    Yes   |          No          |    No    |
| Multi-account per provider      |    Yes   |          No          | Build it |