Connect for platforms

You are adding "Connect to Agentcard" to this platform: our customer (a
company) clicks a button, completes Agentcard's hosted onboarding, returns to
us, and we obtain API credentials to act on their behalf. Implement it
server-side. Never expose secrets or codes to the browser beyond the redirect.

PREREQUISITES
- Our own client_id + client_secret from the Agentcard dashboard
  (Organization -> Developer -> Credentials). Our redirect/return URL must be
  registered as a redirect URI on that client.
- The organization must have the platform capability enabled by Agentcard.
- Base URL https://api.agentcard.sh. All calls are backend-to-backend.

1. PLATFORM TOKEN (cache ~55 min)
POST /api/v2/oauth/token  (x-www-form-urlencoded)
  grant_type=client_credentials & client_id=... & client_secret=...
-> { access_token }. Send `Authorization: Bearer <access_token>` on every call.

2. START A SESSION (when the customer clicks Connect)
POST /api/v2/platform_connect_sessions
  { "return_url": "https://ourapp.com/agentcard/callback", "state": "<random, bound to this customer's browser session>" }
-> 201 { id, url, expires_at, ... }   // store id; redirect the customer to url

3. THE CUSTOMER COMPLETES THE HOSTED FLOW (sign in, pick/create their org).
We receive a redirect: GET <return_url>?code=pcc_...&state=<state>
- Verify state matches what we issued for this browser session (CSRF).

4. EXCHANGE THE CODE (server-side, within 10 minutes; single use)
POST /api/v2/platform_connect_sessions/{id}/exchange   { "code": "<code>" }
-> 200 { organization: { id, name }, client_id, client_secret, test_mode }
Store organization.id + client_id + client_secret encrypted, keyed to our
customer record. The secret is returned ONLY here. The exchange is one-shot:
persist the response before acking — if we lose it, a retry returns
invalid_code and the customer must redo the flow.

5. ACT ON THEIR BEHALF
POST /api/v2/oauth/token with the STORED per-organization credentials
-> an access token scoped to that organization. Use it against /api/v2.
Confirm with GET /api/v2 -> { organization_id } matches organization.id.

STATUS / RECOVERY
- GET /api/v2/platform_connect_sessions/{id} -> { status, connected_organization_id }
  status: pending | bound | completed (code issued, unclaimed) | claimed | expired.
- If the customer abandons the flow (session expires after 60 min), create a
  fresh session next click. If the code expired before exchange, the customer
  re-runs the flow.
- Optional webhook: platform_connect_session.completed fires to our registered
  Agentcard webhook endpoint with { session_id, state, connected_organization_id }
  (never credentials) — treat it as a nudge and still exchange server-side.

ERRORS: { error: { code, message, docs } } — branch on code
(client_credentials_required, platform_not_enabled, invalid_return_url,
invalid_code).