agent-sso: document the colony-sdk helpers (1.29.0 released)#2
Merged
Conversation
The follow-up deliberately left out of #1: colony-sdk 1.29.0 is on PyPI, so get_auth_token() / exchange_token() are installable and can honestly be documented. Adds a Python tab beside the curl in §3b and §5, a compact SDK version of the §9 worked example (where minting and exchanging collapse into one call), and the same in the sdks.md "Build an agent that logs in" section. Also fixes something the page got wrong independently of the SDK release. The SDKs section offered an agent reading THIS PAGE only relying-party libraries — colony-oidc and oauth2-colony are both for the app verifying the token, not the agent obtaining one. So the reader most likely to be here was pointed at the wrong side of the flow, with nothing saying so. The two Python packages have confusingly similar names, so both entries now say which side they are for, and colony-sdk leads. That is the same failure this whole ticket is about: the capability existed, and the place people look did not mention it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs
jackparnell
reviewed
Jul 22, 2026
Review catch by @jackparnell. The line said two things "share the name 'Colony SDK'". They do not. `colony-sdk` is literally named that; `colony-oidc` is not, and nothing describes it that way: * PyPI summary — "an OpenID Connect CLIENT for thecolony.ai" * its README — "a small, framework-agnostic OpenID Connect CLIENT" * this site — sdks.md opens "You do NOT need a Colony-specific SDK — any conformant OIDC client library works", and lists it under "Official clients" So the site deliberately separates SDK from client, and the sentence contradicted a page two clicks away. I invented a naming collision to sharpen the contrast. The confusion it was guarding against is still real — two Colony-published Python packages listed together, doing opposite jobs, and an agent can easily install the relying-party one. Now says that, accurately. The sibling line in sdks.md ("despite similar names") was already correct and is unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The follow-up deliberately left out of #1.
colony-sdk1.29.0 is now on PyPI, soget_auth_token()/exchange_token()are installable and can honestly be documented.What's added
subject_token) and §5 (the exchange).sdks.md→ Build an agent that logs in, which previously just pointed back at the flow page.A separate problem this also fixes
The SDKs section offered an agent reading this page only relying-party libraries.
colony-oidcandoauth2-colonyare both for the app verifying the token, not the agent obtaining one — so the reader most likely to be on an "Agent SSO" page was pointed at the wrong side of the flow, with nothing indicating that.The two Python packages have confusingly similar names (
colony-sdkvscolony-oidc), so both entries now state which side they're for, andcolony-sdkleads.That's the same failure THECOLONYC-555 is about: the capability existed, and the place people look didn't mention it.
mkdocs build --strictpasses.🤖 Generated with Claude Code
https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs