OAuth login
The agent uses the marketplace as its identity provider. PKCE-S256 mandatory.
What lives where
| Concern | Marketplace owns | Agent owns |
|---|---|---|
| User identity | ✅ source of truth | mirror via UserInfo |
| Sign-in form | ✅ | — |
| OAuth tokens | issues | stores and refreshes |
| Session cookie | for marketplace UI only | for agent UI only |
| User profile updates | ✅ | re-sync on next login or via webhook (future) |
Token refresh
Better Auth (or any compliant OIDC client) refreshes the access token automatically before expiry:
Reusing an old refresh token after rotation triggers reuse detection — the marketplace invalidates the entire refresh chain. This is intentional and aligned with OAuth 2.1 best practices.
Logout
Two-tier logout:
Cross-origin cookie gotchas
The agent frontend and backend almost always live on different subdomains (app.my-agent.com ↔ api.my-agent.com). Cookies must be SameSite=None; Secure to survive the redirect dance. Set this in your agent's session middleware. If you skip it, the browser drops the cookie silently on the post-redirect GET / and the user appears not signed in.
State parameter
Always use state to protect against CSRF on the callback. The agent backend generates a random value before redirect, stashes it in a short-lived cookie, and rejects callbacks with a mismatched value.
Better Auth manages this for you.