Authorization Failures

Authorization failures

Some stores ask the buyer to sign in before certain calls will answer. We link the buyer's account with OAuth 2.0 authorization_code and PKCE. These are the ways that can go wrong, and what each one means.

How account linking works

When a store's UCP profile offers account linking (dev.ucp.common.identity_linking), Inspect shows an Account card in its Store view, with the scopes the store asks for. The public Inspector offers the same link from its own banner.

  1. Click Link an account. The store's sign-in page opens in a popup.
  2. You sign in at the store and agree. The store sends you back with an authorization code.
  3. We exchange the code, with the PKCE verifier, for an access token.
  4. The token stays on our server, in your Playground session, for that store's endpoint. Every later call to the store carries it; the trace shows it cut to a prefix.

The token is never saved to your account, and the model never sees it.

When it fails

AuthenticationFailed

JSON-RPC -32000 from a store rejecting a request it could not authenticate: the token ran out, or was never obtained.

FixLink the account again from the Account card in Inspect. A run that hit an expired token can't be picked up again: start a new run after linking.

Sign-in popup blocked

The store's sign-in page opens in a popup, and many browsers block popups. Clicking Link an account seems to do nothing.

FixAllow popups from ucpplayground.com. Chrome shows a blocked-popup icon in the address bar; Safari keeps the setting under Settings → Websites → Pop-up Windows.

Account missing in another browser

The token belongs to your Playground session, so another browser or a private window starts with no account linked. Tabs in the same browser share it.

FixLink the account again in that browser.

PKCE verification failed

The code_verifier sent at exchange does not match the code_challenge from the authorization request. This should not happen in normal use.

FixThis one is ours. Unlink and try again; if it keeps happening, send us the link to the run or Inspect session.

Redirect URI mismatch

The store's authorization server rejected the return address because its OAuth client does not list ours.

FixThe store owner adds ucpplayground.com/oauth/callback to the client's allowed redirect URIs. Stores that require HTTPS redirect URIs (UCPReady does) reject local-dev return addresses by design.

When the store asks for an account

When an operation needs a signed-in buyer, the store answers with an RFC 6750 challenge. That is the store answering correctly, not a failure: a run's page doesn't count it against the store or the agent.

ChallengeWhat happenedWhat to do
identity_requiredNo linked account, for an operation that needs one. Link an account, with the scopes the store declares.
insufficient_scope An account is linked, but the operation needs more permissions. Link again, asking for the full scope set named in the challenge.
invalid_tokenThe linked account's token is no longer valid.Link the account again.

In Inspect, a refused order lookup shows the store's code and points you to the Account card; link the account, then look up again. The public Inspector shows a banner with Link Account, Re-authorize or Reconnect Account, and re-runs the refused call after you link. If your account already has every scope the challenge names, it does not retry: that points at the store's scope set-up, not a missing grant.

Warning

A linked account lasts only as long as your Playground session. Signing out, clearing cookies, or a private window all mean linking again.

Checking the link

On Runs and in Inspect, the header's account chip shows the account linked at the store in scope: No account linked, Linked with the time left on the token, or Link expired. Open it to see the account, the endpoint, the scopes and the token's state, or to unlink. Check it before you read a failed run as the store's fault.

Something wrong on this page?