Skip to content

docs(identity-linking): say how a business answers a token it rejects on an ungated operation - #1044

Open
evoleinik wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
evoleinik:docs/invalid-token-ungated-ops
Open

evoleinik wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
evoleinik:docs/invalid-token-ungated-ops

Conversation

@evoleinik

Copy link
Copy Markdown

Description

Adds one paragraph to identity_required. It covers an operation that no scope in config.scopes gates, when the request carries a user identity token anyway.

A business that rejects that token SHOULD answer as it would for a gated operation: 401, error="invalid_token", and identity_required. That is the answer RFC 6750 §3.1 gives for an invalid token. A business MAY instead ignore the token. The paragraph says so, and says the platform then can't tell why it got that answer.

Scopes stays as it is: "The business defines the access policy for non-scoped operations; UCP does not prescribe a default." A business still decides who can call the operation, and whether it looks at tokens at all.

Why it matters: the Access Levels table puts personalized pricing at the user-authenticated level, and a catalog search can be ungated. A platform may send a token there to get one buyer's prices. If the token was revoked and the business quietly drops it, the platform sees the public view. It can't tell a revoked token from a buyer who doesn't qualify for those prices. A 401 with invalid_token lets it refresh the token or retry without it.

The body keeps identity_required, the code gated operations already use, because a new code would change the schema.

We do this in a B2B seller integration that shows NDA-gated prices after identity linking. Background is in #1028. If maintainers read this as a protocol change, I'll move it to an Enhancement Proposal.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

Discussion: #1028

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

🤖 Drafted with Claude Code. I checked it against the spec and tested our server's behavior.

@evoleinik

evoleinik commented Nov 12, 2026 •

Copy link
Copy Markdown
Author

Two open items now lean on this paragraph. Proposal #1047 says a business that rejects the token answers 401 with identity_required, and points here for ungated operations. Its draft spec page, #1059, asks whether to wait for this PR. Conformance PR Universal-Commerce-Protocol/conformance#125 can test the rule once it lands. Today its token test covers only gated operations.

The question in the description still stands. If maintainers would rather see this as an Enhancement Proposal, I'll move it.

@damaz91 damaz91 added documentation Improvements or additions to documentation status:under-review gov:needs-tc-review Requires review and approval from the Technical Council area:common Issues and pull requests related to common protocol schemas and specifications and removed status:needs-triage Signal that the PR is ready for human triage labels Nov 12, 2026
@damaz91 damaz91 moved this to Triage / Unscheduled in DTC Review Pipeline Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:common Issues and pull requests related to common protocol schemas and specifications documentation Improvements or additions to documentation gov:needs-tc-review Requires review and approval from the Technical Council status:under-review

Projects

Status: Triage / Unscheduled

Development

Successfully merging this pull request may close these issues.

2 participants