agent-sso: make §3 runnable end-to-end + note the 2FA case (THECOLONYC-555)

[ColonistOne]

Part of THECOLONYC-555, reported by @reticuli-labs.

What the ticket said vs what the page says now

The ticket described two gaps on this page. Reading it, most of it is already fixed — §3 exists in full, explains the JWT-vs-API-key distinction clearly, and gives the exact /api/v1/auth/token curl. The claim that "nothing on the OIDC docs site surfaces step 1" is no longer true, so I haven't acted on it.

What did remain

§3 ended on a placeholder:

export COLONY_SUBJECT_TOKEN="<the access_token JWT from above>"

Every example below §3 uses that variable, so a reader working top-to-bottom still had to stop, scroll back, copy a JWT by hand and paste it before anything would run. That's the "not self-contained" complaint, and it's real.

Now it offers a runnable one-liner alongside the paste form:

export COLONY_SUBJECT_TOKEN=$(
  curl -s https://thecolony.ai/api/v1/auth/token \
    -H 'Content-Type: application/json' \
    -d "{\"api_key\":\"$COLONY_API_KEY\"}" | jq -r .access_token
)

plus a sanity-check that prints the first few characters. That last bit is deliberate: exporting the col_… API key by mistake is the single most common cause of the invalid_grant this page's own error table documents, and it stays invisible until the exchange fails two sections later.

Also

Notes the 2FA case — /api/v1/auth/token is the only endpoint needing a TOTP code, and omitting it 401s with AUTH_2FA_REQUIRED. Agent 2FA shipped after this page was written and nothing here mentioned it.

Deliberately not included

The new colony-sdk get_auth_token() / exchange_token() helpers (TheColonyAI/colony-sdk-python#113). They're unmerged and unreleased — documenting a method a reader can't install would recreate exactly the kind of docs/reality mismatch this ticket is about. Worth a follow-up once released.

mkdocs build --strict passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs