Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Claude Code is Anthropic’s CLI for coding agents. Authsome integrates with Claude Code through the /anthropic-skills:authsome skill. Once installed, Claude can log in to any provider, list connected services, and run agents that pull fresh credentials from the local vault.

Set up authsome in Claude Code. Paste this prompt to install the skill and authenticate a first provider.

​
What the integration gives you

  • One login per service. OAuth2 and API-key flows run from inside Claude Code. The skill drives the same uvx authsome login commands a human would type.
  • No credentials in prompts or files. Claude never sees raw tokens. The skill calls authsome, which collects secrets through a local browser bridge or the masked terminal fallback.
  • Automatic refresh. Tokens stay fresh for every agent run Claude triggers. You do not re-authenticate when an access token expires.
  • The same vault. Connections you create through the skill are stored in ~/.authsome/, identical to connections created from the regular CLI. Nothing is duplicated.

​
Install the skill

The authsome repository ships a Claude Code skill at skills/authsome/SKILL.md. Install it into your local Claude Code skills directory: 
git clone https://github.com/agentrhq/authsome.git /tmp/authsome
mkdir -p ~/.claude/skills
cp -r /tmp/authsome/skills/authsome ~/.claude/skills/
In Claude Code, invoke the skill by name once it’s installed: 
Use the authsome skill to log me into GitHub.
Claude will read the skill manifest and run the appropriate uvx authsome commands. The skill teaches Claude the list → login → run flow plus authsome’s safety rules (no client_secret in shell history, no --scopes workaround for missing access, etc.).

​
First run

A typical first session looks like this:
1

Ask Claude what's already configured

/anthropic-skills:authsome list
Claude runs uvx authsome list and reports which providers are bundled, configured, and connected.
2

Log in to a provider

Log in to GitHub via authsome.
Claude opens a browser to the OAuth2 PKCE flow. You approve the requested scopes, the callback lands on http://127.0.0.1:7998/auth/callback/oauth, and authsome stores the encrypted record.
3

Use the connection

Use authsome to fetch my last 5 GitHub notifications.
Claude runs the agent under uvx authsome run. The HTTP proxy injects the Authorization header at the api.github.com host. The agent’s environment never contains the raw token.

​
Common prompts

Concrete requests Claude understands. Each one maps to a specific authsome command.
PromptWhat Claude runs
”Log me in to GitHub via authsome.”uvx authsome login github
”Use the Resend API key from authsome to send an email.”uvx authsome run -- python <script>
”Switch the active GitHub connection to my work account.”uvx authsome login github --connection work
”Show me which providers are connected.”uvx authsome list
”Revoke my OpenAI key.”uvx authsome revoke openai
”Add a custom provider for Acme CRM.”uvx authsome register ./acmecrm.json

​
Why this is the safe pattern

Without authsome, agents inside Claude Code typically read tokens from environment variables, .env files, or shell history. Each of those surfaces leaks easily:
PatternToken visible in
export GITHUB_TOKEN=...ps, /proc/<pid>/environ, shell history, subprocess env
.env file in the repoThe repo, backups, git history if committed by accident
Manual paste into ClaudeClaude’s transcript
uvx authsome run -- ...None of the above
authsome run is the recommended pattern for any Claude Code agent that calls third-party APIs. The child process never sees the real secret because the proxy injects headers at request time.

​
Embedding the library

If you’re orchestrating Claude Code from a larger Python program and want to inject credentials before launching Claude, you can drop below the skill into the library: 
from authsome.server.dependencies import create_auth_service

auth = create_auth_service()
token = auth.get_access_token("github", connection="default")

# pass `token` to your client of choice
Or use the proxy without library access: 
uvx authsome run -- python my_agent.py
The library is documented in Python library reference.

​
Multi-account workflows

Most real workflows need at least two accounts (personal and work GitHub, or a personal and team OpenAI key). The skill plays well with named connections: 
Log me into GitHub as my work account.
Claude runs: 
uvx authsome login github --connection work
Read it back: 
Use the work GitHub connection to open a PR.
Claude runs: 
uvx authsome get github --connection work --field access_token --show-secret
For the underlying model, see Profiles vs connections.

​
What the skill cannot do

  • It cannot type a client_secret for you. Authsome refuses sensitive values as command-line arguments. The browser bridge is the only path.
  • It cannot bypass the proxy CA requirement. HTTPS interception needs the mitmproxy CA trusted on the machine. The first authsome run writes the CA to ~/.mitmproxy/. See Proxy networking.
  • It cannot share the vault across machines. Claude Code on a second machine has its own ~/.authsome/. Re-run logins there, or use a hosted daemon (see Hosted deployment model).

​
Troubleshooting

If a Claude-driven login hangs:
  • Run uvx authsome doctor directly from the terminal to surface initialization errors.
  • Run uvx authsome --verbose login <provider> to see the full flow including the daemon round-trips.
  • Check ~/.authsome/audit.log for the most recent action and outcome.
For provider-specific errors, see OAuth callbacks and Token refresh.

​
What’s next

Run agents with the proxy

The proxy injection model the skill uses under the hood.

Python library

Drop below the skill into AuthService for fine-grained control.

All bundled providers

Every service Claude can log you into out of the box.

Custom providers

Add a provider authsome doesn’t ship.