Path 2 now offers two tracks: GitHub + OpenAI for users who want a
runnable demo, and Notion via MCP for the zero-setup case (DCR
auto-registers a client, no OAuth app needed). Each track is a tab.
The GitHub + OpenAI track ends in a minimal agent script that stars
agentrhq/authsome and asks gpt-5 to write a one-line celebration.
It uses only the standard library so there's nothing to pip install.
The script lives inside an Accordion so it doesn't dominate the page
for readers who only want to see how the login flow works.
Also clarifies what the OAuth bridge stores versus the access token
GitHub returns, since that confused readers who thought they'd need
a separate PAT to make API calls.
New users hit `authsome login github` in the quickstart without
knowing GitHub requires them to register an OAuth app first. The
existing Tip mentioned client_id and client_secret were needed but
not how to obtain them, so first-timers got stuck.
The quickstart's CLI-driven path now has a "Register the GitHub
OAuth app" section before the login steps. It covers the developer
settings page, the form fields (Authorization callback URL must be
exact; Device Flow on), and a warning to save the Client Secret
before navigating away (GitHub shows it once). The login steps
were reordered into four: run login, paste credentials in the
local bridge, approve on GitHub, confirm.
The same walkthrough is mirrored in integrations/oauth/github.mdx
Prerequisites so the per-provider page stays the canonical
reference. Both pages share a single screenshot of the local bridge
form at /images/login-github-authsome.png.
The credential-storage and profiles-vs-connections pages described
profiles as separate SQLite files under ~/.authsome/profiles/<name>/
with per-profile flock locking. The actual implementation moved to
a single DiskStore at ~/.authsome/server/kv_store/ with profile
names used as key prefixes, and the daemon is the only writer.
The storage layout trees on both pages drop the profiles/ folder
and now reflect the canonical layout in reference/file-layout.mdx.
The 'Locking' section is replaced with a Concurrency section that
explains the daemon as single writer; the per-profile flock story
is gone. The 'at a glance' table now describes profiles as key
prefixes in a shared store. The OAuth client-credentials row moves
from per-profile to server-scoped (server:<provider>:client),
matching how the daemon actually stores them. 'Which one is active'
now says explicitly that a profile is an identity handle scoped
through the PoP token.
PR #281 is the upstream rename of "profile" to "principal"; this
PR keeps the existing terminology to land cleanly ahead of that
bigger naming change.
The skill rewrite (PR #284) and README update standardized on
"authsome <command>" (assumes "uv tool install authsome") and on
agent-driven login flows. The docs site still spoke "uvx authsome"
everywhere and didn't surface the auth-error decision tree the
skill teaches. This brings the docs in line.
Four kinds of change in one PR.
1. CLI prefix sweep ("uvx authsome" to "authsome").
Mechanical find/replace across docs/site/ excluding installation.mdx.
812 occurrences updated. installation.mdx keeps the literal "uvx"
references because they explain the one-off run path.
2. installation.mdx rewrite.
- "uv (recommended)" tab leads, with "uv tool install authsome".
- pip second.
- uvx demoted to "one-off, no install" with @latest pattern shown.
- From source unchanged.
- A Note at the top declares: every command in the docs is the
installed form; uvx users prefix with "uvx authsome@latest".
- All subsequent code blocks updated to bare "authsome".
3. New troubleshooting/auth-errors.mdx page.
Captures the decision tree the skill teaches: 401 -> revoke +
re-login; 403 -> "authsome login --scopes" (not re-registering);
wrong client creds -> "authsome remove" then re-login. Registered
in docs.json under Troubleshooting.
4. quickstart.mdx pivoted to two paths + help reflex.
Path 1: agent-driven. Install the skill, ask the agent to do a
task that needs an external service. The agent runs login itself.
Path 2: CLI-driven. The existing manual walkthrough, preserved.
Adds a Tip about reading "authsome --help" and "authsome <cmd>
--help" before guessing flags.
5. Agent-mode note on the four skill-based integration pages.
claude-code, codex, cursor, opencode each get a one-paragraph Note
clarifying that the agent runs login, opens the browser on the
user's machine for OAuth, and that users should not paste keys
into prompts or pre-run login commands. The four SDK-style
integration pages (langchain, llamaindex, openai-agents-sdk,
anthropic-sdk) are unchanged because their pattern is
developer-driven, not agent-driven.
Verified clean: no "uvx authsome" outside installation.mdx,
docs.json valid, no em-dashes introduced.
Two classes of bugs corrected, both verified against main at 69a0cb9.
Skill (skills/authsome/references/adding-provider.md):
- OAuth redirect URL was http://localhost:7999/callback. Source truth
is http://127.0.0.1:7998/auth/callback/oauth (server/urls.py:8-9
and the matching user-facing doc in custom-providers.mdx). Agents
following the skill would tell users to register OAuth apps with
a redirect URI that does not match what authsome actually serves,
causing every PKCE login to fail.
- Step numbering had two "3." entries and no "4."; renumbered.
- Provider registration link pointed at the stale
raw.githubusercontent.com/manojbajaj95/authsome fork; repointed
to agentrhq.
Stale repo owner in actively-rendered surfaces:
- CONTRIBUTING.md: git clone URL.
- docs/site/README.md: link to the repo.
- docs/site/reference/bundled-providers.mdx: "open a pull request
against" link in the upstream contribution section.
- docs/site/concepts/credential-storage.mdx: replaced
"manojbajaj95" example label with "octocat" so the sample
connection record reads as a generic GitHub username.
- src/authsome/ui/templates/_layout.html: dashboard sidebar
"Support" link and topbar "GitHub" button.
- src/authsome/ui/templates/overview.html: dashboard "Contact Us"
button on the overview page.
Out of scope:
- pyproject.toml author attribution stays as Manoj Bajaj; that is
the actual maintainer's name, not a stale fork reference.
- CHANGELOG.md has ~100 manojbajaj95 commit URLs but release-please
regenerates it; manual edits would be overwritten on next release.
Per-agent access control and firewall rules were not shipped — move back
to Coming next. Available today now reflects only changelog-confirmed
features. Add multi-user support to Coming next.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: cd99c854018c
- doctor: fix spec_version always showing FAIL — server returned the version
number "3" instead of "ok", so the CLI check `val == "ok"` always failed
on healthy installs
- register --force: was not skipping the confirmation prompt; --force now
implies --yes so a single flag covers both server-side overwrite and client
prompt bypass (matching gh/fly/docker convention)
- --quiet: was silencing ALL output including primary data rows; add emit()
to ContextObj (never quiet-suppressed) and use it for list table rows and
doctor check lines — informational headers remain quiet-suppressible
- log: switch from raw loguru client log to structured server audit log
(NDJSON); display as human-readable table with timestamp/event/provider/
status columns; --raw flag retains access to the client debug log
- add CLI design review report at docs/internal/cli-design-review.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: e28262984429
The earlier audit surfaced contradictions between docs and code that
were verified against agentrhq/authsome main at 3929b86. This fixes
the verified gaps; the rest is tracked for follow-up PRs.
Provider count: source has 45 JSONs (14 OAuth2 + 31 API key) in
src/authsome/auth/bundled_providers/. Notion ships as two entries
(notion + notion_dcr) and Klaviyo as two (klaviyo + klaviyo-oauth).
- README.md: 44 -> 45 and 13 OAuth -> 14 OAuth.
- .claude-plugin/marketplace.json: same correction in the plugin
description.
Master key path: paths.py routes the server master key to
~/.authsome/server/master.key, confirmed by vault/crypto.py and
health.py. Three doc pages had the wrong (top-level) path.
- security/threat-model.mdx: data-at-rest table and offline-disk
paragraph.
- security/encryption.mdx: local_key backend description.
- troubleshooting/doctor.mdx: both accordion FAIL examples and the
chmod remediation. Also points users at "authsome init" instead of
the side-effect-on-first-run workaround.
- concepts/credential-storage.mdx: local_key backend description.
- concepts/architecture.mdx: vault wrapping description.
Architecture layer status: src/authsome/ ships identity/ (Ed25519
keys, did:key DIDs, PoP JWT), audit/ (structured JSON events), in
addition to vault/ and auth/. Only policy/ is still planned.
- concepts/architecture.mdx: replace the "alpha focuses on Vault and
Auth" Note with a per-layer status table reflecting reality. Also
updates the SQLite backend description to the kv_store path
(~/.authsome/server/kv_store/) consistent with the canonical
filesystem layout.
Hosted daemon cross-reference: changelog 0.2.4 ships
AUTHSOME_DAEMON_URL and AUTHSOME_SERVER_BASE_URL, but the threat
model classifies hosted daemons as "Caveat (VPN only)" for private
and "No" for public. Cross-reference added to the changelog entry so
adopters see the constraint at the point of the feature
announcement.
Domain: README links updated from authsome.agentr.dev to
authsome.ai for consistency with the docs canonical URL fixed in
#271.
Out of scope (separate follow-ups):
- Profile-as-folder trees in credential-storage.mdx and
profiles-vs-connections.mdx still show profiles/<name>/store.db,
which conflicts with the new server/kv_store/ architecture. Needs
a dedicated rewrite of those pages.
- mitmproxy CA install procedure (10 pages mention it; none have an
install command).
- Anthropic bundling.
- Marketing site sitemap on authsome-web.
Mintlify generates the sitemap from seo.metatags.canonical, and the
canonical was still pointing at authsome.agentr.dev. Every <loc> in
https://authsome.ai/docs/sitemap.xml carried the old domain even
though the docs are now hosted at authsome.ai.
Domain rename:
- docs.json canonical to https://authsome.ai/docs.
- docs.json footer "Home" link to https://authsome.ai.
- custom-providers.mdx schema URL to authsome.ai.
Security disclosure:
- Drop the security@agentr.dev email path from disclosure.mdx and
route all reports through GitHub's private security advisory flow.
The email was the only contact path that needed mailbox
maintenance; GitHub advisories give us the same private channel
without it.
Dead links (target files deleted upstream in 019bdd1 and ec06181):
- roadmap.mdx: drop both references to docs/authsome-design.md
(moved to docs/internal/, not public-facing).
- daemon-trust-boundary.mdx: replace authsome-design.md reference
with a link to the public /roadmap page.
- encryption.mdx: drop docs/specs/authsome-v1.md reference; keep
the prose describing the future portable spec.
- credential-storage.mdx: same fix as encryption.mdx, also drops
one stale manojbajaj95 owner reference incidentally.
Navbar previously rendered "Authsome" as plain text with no logo or
favicon. This adds the Authsome `#` mark + wordmark as SVG logos (light
and dark variants), a favicon, and a Discord community link. The PyPI
link gets a Python brand icon, and Discord moves into footer socials
alongside GitHub.
llms.txt drops out of the navbar — it already lives in the footer's
Docs column, and the navbar slot is more valuable for the community
link.
Profile is now a pure credential namespace scoped by the Identity handle,
not an independently managed entity. The two were always 1:1 but modelled
as separate concepts; this commit makes that explicit.
Key changes:
- Add `active_identity` to GlobalConfig; `ensure_local_identity` reads it
and errors hard if the configured handle is missing on disk (no silent
re-creation)
- `authsome init` writes `active_identity` to config after registration
- Collapse `registered: bool` + `registration_status: str` on
IdentityMetadata into a single `registered: bool`; add `mark_registered()`
- Remove vestigial `Identity` dataclass, `DEFAULT_IDENTITY`, `current()`
- Remove `name`, `description`, `owner_email` from IdentityMetadata (deferred
to hosted version)
- Remove `ProfileMetadata`, `ProfileNotFoundError`, `create_profile`,
`list_profiles`, `get_profile`, `set_default_profile`, `default_profile`
shim in save_config — profile is a side-effect of identity registration
- Add hard-error test for missing configured identity
- Update UBIQUITOUS_LANGUAGE.md, AGENTS.md architecture section, and
ADR 0002 to reflect current code (fix stale AuthsomeContext, AuthClient,
config.json path, ProfileMetadata references)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: 614885258a45
Make the daemon identity registry authoritative for protected PoP requests and remove implicit default-profile identity behavior.
Store daemon-owned state under server/ while keeping CLI signing identity files under identities/.
BREAKING CHANGE: Existing implicit default-profile installs must run authsome init again; profile:default credentials are not migrated.
Entire-Checkpoint: 557455816515
Across the docs the recommended pattern is now wrapping the agent with
`uvx authsome run --`. The Python library remains supported but is
positioned as the embedding case for orchestrators that need explicit
control.
Concrete changes:
- Every provider CodeGroup (45 pages) reordered to Proxy →
Environment → Python library, with a one-line lead-in.
- Generator updated so future regenerations preserve the order.
- Agent integration pages reframed: "Pattern 1 / Pattern 2" headings
replaced with "Run under the proxy" + "Embedding the library".
- index.mdx for agent frameworks no longer presents two equal patterns.
- reference/python-library.mdx adds a top callout pointing readers at
the CLI + proxy as the supported surface.
- concepts/architecture.mdx re-frames Sidecar as the supported mode
and Library as an embedding option that shares the same layers.
Top nav now has four tabs:
- Documentation (Get started · Concepts · Security · Project)
- Guides (Guides · Troubleshooting)
- Reference
- Integrations
Troubleshooting is folded as a sub-group under Guides since both are
task-oriented.
The <Frame> component constrains its child to a narrow centered column.
That works for images and mermaid (which renders as SVG and scales),
but it squeezed the architecture page's text-based call graph into a
single-character column, making it unreadable.
Replaced the wrapper with a plain caption sentence above the code block.
The mermaid Frame in index.mdx stays since mermaid SVGs handle the
constraint correctly.
The snippet was deleted in 50f016c (now bf5f65c after rebase) when its
content was folded into the CodeGroup trailer. The generator continued
to emit the now-broken import line at the top of every provider page,
which Mintlify surfaced as warnings on every page load.
Regenerated 43 pages plus the Postiz override that lost its custom
"What's next" cards in the regen.
Tier 1 (critical — users were misconfiguring):
- Port + callback URL fixed everywhere. All `127.0.0.1:7999/callback`
references replaced with `127.0.0.1:7998/auth/callback/oauth`, the
value actually used by `src/authsome/server/urls.py`.
- Python API rewrite. Removed every reference to the non-existent
`AuthsomeContext` and `ctx.auth.*` API. Library code samples now use
`create_auth_service()` from `authsome.server.dependencies`, returning
the real `AuthService`. Exception names corrected (the public exports
in `authsome/__init__.py` all use the `*Error` suffix).
`reference/python-library.mdx` rewritten end-to-end against the real
surface; provider CodeGroup blocks regenerated with the corrected
pattern.
- Dashboard URLs corrected. `/overview`, `/connections`, `/app/...`
replaced with the real `/ui/`, `/ui/connections`, `/ui/apps/...`
(matches the `/ui` prefix in `server/routes/ui.py`).
- `profiles-vs-connections.mdx` no longer claims a separate audit log
per profile. The file at `~/.authsome/audit.log` is shared and tagged
with the profile name.
Tier 2 (significant):
- `reference/cli.mdx` expanded with `scan`, `connection set-default`,
`ui`, and the `daemon` subcommand group (`serve`, `start`, `stop`,
`restart`, `status`, `logs`). Replaced the bogus `okta` example with
GitHub Enterprise.
- `reference/audit-log.mdx` event table corrected: the documented
`refresh` event with an `outcome` field doesn't exist; the real event
is `refresh_failed` with `error` and `fallback_available`. Added the
`scan` event.
- OAuth index: broken `/integrations/oauth/klaviyo` link fixed to
`klaviyo-oauth`. Linear row corrected to `pkce` with the real regex
host. Notion DCR host fixed to `mcp.notion.com`.
- Linear page no longer claims DCR support (the JSON has
`supports_dcr: false` and `flow: pkce`).
- Provider count drift fixed in `index.mdx`, `provider-registry.mdx`,
and `bundled-providers.mdx` (which was also missing the `notion_dcr`
row).
Tier 2.7 (integration page corrections):
- `claude-code.mdx`: replaced fabricated `/anthropic-skills:authsome`
namespace and `npx skills add` command with the real installation
procedure for the bundled `skills/authsome/SKILL.md`.
- `cursor.mdx`: link to cursor.com (was cursor.sh); rewrote the
terminal-tool advice against Cursor's real MCP config in
`~/.cursor/mcp.json`.
- `cowork.mdx`: removed unverified `github.com/cowork-ai` link.
- `nanoclaw.mdx`: framed the runners more honestly; code example no
longer assumes a specific `Agent` import.
- `anthropic-sdk.mdx`: model ID `claude-sonnet-4-6` → `claude-sonnet-4-5`.
Tier 3 (API-key dashboard URLs):
- 18 stale or wrong dashboard URLs reviewed. Five providers without a
canonical key-management page (clearbit, g2, mailchimp, mention-me,
wistia) now show a `docs` link plus a one-line note explaining why.
The rest point at verified URLs as of May 2026. Changes flow through
the generator's `APIKEY_NOTES` map and the regeneration of all 43
provider pages.
Tier 4 (filler / repetition):
- CA-install instructions consolidated to canonical location in
`troubleshooting/proxy-networking.mdx`; `installation.mdx` and
`run-agents-with-proxy.mdx` link instead of duplicating.
- "Override bundled provider" deduplicated (canonical in
`custom-providers.mdx`; removed from `provider-registry.mdx`).
- "Known v1 limitations" canonical in `daemon-trust-boundary.mdx`;
trimmed from `threat-model.mdx`.
- `quickstart.mdx` H2 duplicate dropped; export-sourcing instruction
corrected to use `eval`.
- `troubleshooting/doctor.mdx` removed "Inspect specific state" block
that duplicated `cli.mdx`.
- `concepts/the-daemon.mdx` "When the daemon is reused" subsection
promoted into the lifecycle body.
- `run-agents-with-proxy.mdx` "Limitations" H2 absorbed into one line.
- Postiz cross-linked with `headless-device-code.mdx` and vice versa.
- New "Uninstall" section in `installation.mdx`.
CodeGroup across all 45 provider pages: the "Use the token / key" section
now collapses Library / Proxy / Environment into a single tabbed widget
instead of three sequential subsections. Higher information density, one
copy-paste interaction per page.
Expandable on the daemon-api /ready response: nested checks fields render
as a typed, collapsible block instead of inline prose.
The proxy-injection.mdx snippet is no longer referenced anywhere; its
content is folded into the CodeGroup trailer prose with the env-var and
host inlined per page. Removed.
Priyansh Khodiyar