Authorization Failures
Some targets require OAuth2 before their tools will answer. The harness runs authorization_code with PKCE — these are the five ways that handshake goes wrong, and what each one means.
How authorization runs
When a target's manifest declares an authorization server, the harness prompts you before the first tool call. The token is kept only with your browser session; it is not saved to your account.
- The harness opens the store's consent screen in a popup.
- You grant permission; the store redirects back with an authorization code.
- The code plus a PKCE verifier is exchanged for an access token.
- The token is held with your browser session and rides on every subsequent tool call.
When it fails
JSON-RPC -32000 from the target rejecting an unauthenticated request — the token expired or was never obtained.
FixRe-authorize from the header. A token that expired mid-session needs a new session after re-authorizing; the old one cannot be resumed.
The consent screen opens in a popup and most browsers block popups by default. Clicking Authorize appears to do nothing.
FixAllow popups from ucpplayground.com. Chrome shows a blocked-popup icon in the address bar; Safari keeps it under Preferences → Websites → Pop-up Windows.
Tokens are bound to your browser session, so another browser or a private window starts with nothing stored. Tabs in the same browser share it.
FixAuthorize again in that browser.
The code_verifier sent at exchange does not match the code_challenge from the authorization request. This should not happen in normal operation.
FixOurs, not yours. Clear the session and retry; if it persists, send support the session ID.
The authorization server rejected the callback because it is not a registered redirect URI — the target's OAuth client does not list ours.
FixThe store owner adds ucpplayground.com/oauth/callback to the client's allowed redirect URIs. Merchants requiring HTTPS redirect URIs (UCPReady does) will reject local-dev callbacks by design.
Identity-linking re-authorization
When a protected operation needs a user identity (per a target's dev.ucp.common.identity_linking declaration), the store answers with an RFC 6750 challenge. The harness reads the challenge and offers the matching action.
| Challenge | What happened | Banner offers |
|---|---|---|
identity_required | No linked account for an operation that requires one. | Link Account, requesting the declared scopes. |
insufficient_scope | Linked, but the operation needs more permissions. | Re-authorize, requesting the full scope set named in the challenge. |
invalid_token | The linked session is no longer valid. | Reconnect Account. |
After re-authorization the operation that triggered the challenge is re-run automatically. If your account already grants the exact scopes named, the harness does not retry — that points at a store-side scope configuration issue, not a missing grant.
Tokens last only as long as your browser session. Signing out, clearing cookies, or a private window all mean re-authorizing.
Checking token status
On an authorized target the header carries the token indicator: green for a valid token, red or absent once it has expired. Check it before reading a failed session as a target's fault.