authsome

Authsome

Your outbound HTTPS traffic is transparently proxied through the Authsome,
a proxy service that injects stored credentials as HTTP headers. You never
see or handle credential values directly.

How to Access External Services

You have direct HTTP access to external APIs. OAuth apps (Gmail, GitHub,
Google Calendar, Google Drive, etc.) and API key services are all available
through the gateway. Just make the request by appending authsome run -- to
any bash command; the gateway injects credentials if the app is connected.

Making Requests

Call the real API URL. The gateway intercepts the request and injects
credentials automatically.

authsome run -- <command>
authsome run -- curl -s "https://api.github.com/user/repos?per_page=10"
authsome run -- python my_agent_script.py

Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) all
honor the HTTPS_PROXY environment variable automatically. You do not need
to set any auth headers.

---

Login Flow

• Run authsome login <provider> via Bash yourself — do NOT ask the user to
  run this. The browser opens on their machine; they complete OAuth without touching
  the terminal.
• Poll the status of the login using authsome provider list after a few seconds
  • If connected — proceed normally.
  • If not yet connected — display the authentication URL to the user, ask them to complete the login in their browser, and report back once done. Once the user confirms, run authsome provider list again to verify the connection before continuing.

---

When a Request Fails

If authsome is not installed on the agent's machine:

Install authsome using uv tool install authsome

Only when uv tool install fails, use fallback: pipx install authsome or uvx authsome@latest <command> for one-off use (say when running inside sandboxed environments).

If you get an authentication error (401, 403) follow this decision tree:

1. Run authsome provider list to see all providers and their connections

2. If relevant provider exists but it has no connections → start the login flow

If there is a login error due to wrong client id/client secret you can delete the provider via authsome provider remove <provider> and start the login flow

3. If relevant provider exists and it is connected

For 401 error → you need to re-login, creds have expired

• revoke the creds using authsome provider revoke <provider>
• then start the login flow

For 403 error → you need to re-login, with the correct scopes, or missing permissions
CRITICAL: Do NOT register a new provider just to add scopes; always use --scopes with the existing provider:

authsome login <provider> --scopes repo,user,gist

4. If relevant provider does not exist, then → add it first and then start the login flow

Adding a new provider

See references/adding-provider.md.

---

Troubleshooting & Help

If you are unsure of the correct command syntax, need to check available flags, or if a command fails, ALWAYS read the built-in help menus before guessing:

authsome --help
authsome provider --help
authsome connections --help
authsome run --help

Rules

• Never say "I don't have access to X" without first making the HTTP
  request through the proxy.
• Never use browser extensions, gcloud, or manual auth flows. The
  gateway handles credentials for you.
• Never ask the user for API keys or tokens directly. Run authsome login <provider>. It opens a browser window and captures them directly, so secrets
  never enter the conversation.
• Never suggest the user open Gmail/Calendar/GitHub in their browser
  when they ask you to read or interact with those services. You have API
  access. Use it.
• Never use any workflow that prints tokens or API keys to the terminal.
  Use authsome run -- ... instead.
• If the gateway returns a policy error (403 with a JSON body), respect
  the block. Do not retry or circumvent it.
• If the skill fails, the goal took too many steps, the CLI behaved unexpectedly,
  or the user asks you to report an issue — file a bug following
  references/feedback.md.
• Never ask the user to run commands in their terminal that you can run yourself.