Repository navigation
Implementer notes: buyer eligibility for NDA-only B2B prices through identity linking #1028
evoleinik
started this conversation in
Show and tell
Replies: 1 comment
|
Question 3 is now a docs PR: #1044. If maintainers would rather see it as an Enhancement Proposal, I will move it. |
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
We run the Business side of UCP for a B2B software seller that shares list prices only under NDA. The catalog is public, but prices are not. A buyer's agent sees prices only after the buyer links a verified work email and accepts the seller's NDA.
These notes provide one data point on buyer eligibility, a Phase 1 item in the B2B charter (#947). They also show where eligibility is not yet machine-readable. A platform can tell from
identity_optionalthat signing in unlocks more. No field tells it what eligibility requires, or that a signed-in buyer is still waiting for approval. Those arrive only as prose.This implementation is deployed for one seller on UCP 2026-08-25. A daily check using a test buyer we control exercises both the public and linked paths. In a separate test, a general-purpose AI assistant that had never seen our code ran the whole flow as the platform. It signed in with another vendor's public client document, and our own staff acted as the buyer. No real buyer has linked yet, so please read this as design feedback rather than usage data. Hosts, the seller's name, and the buyer's address are placeholders below.
How it works
dev.ucp.common.identity_linkingwithconfig.scopes: {}. The authorization server metadata listsdev.ucp.shopping.catalog.search:readanddev.ucp.shopping.catalog.lookup:readinscopes_supported. That uses the spec's optional layer. Search and lookup work without sign-in, and sign-in adds prices.identity_optional, which points to the protected resource metadata. A price filter from an unlinked caller returns no products and aprice_filter_unsupportedmessage, so a caller cannot narrow down a hidden price by range.none) and identify themselves with a Client ID Metadata Document. Each seller has its own issuer, and the server returnsiss(RFC 9207). The sign-in page has three steps. First, the buyer enters a work email, and free-mail domains are rejected. Next, the buyer opens the NDA email, accepts the NDA as a named signer, and enters the code shown there. Finally, the buyer grants access. The consent screen names the client and its domain, and states that access does not place an order.Cache-Control: private, no-store.An invalid token returns
401withidentity_requiredand aWWW-Authenticatechallenge. Question 3 is about that choice.The message codes
price_on_request,price_filter_unsupported, andnda_confidentialare our own, as UCP does not define them. The no-price case is #877, now proposed in #969.Example responses (trimmed, placeholders in angle brackets)
Public search, no token:
{ "products": [{ "id": "<product>", "variants": [{ "id": "<product>:default" }] }], "messages": [ { "type": "info", "code": "identity_optional", "content": "Sign in with a work email under <seller>'s NDA to see annual pricing. Sign-in metadata: https://<host>/.well-known/oauth-protected-resource/ucp/<seller>" }, { "type": "warning", "code": "price_on_request", "presentation": "disclosure", "path": "$.products[0]", "content": "<seller> quotes this product on request. No list price is published. Ask the seller, or request a quote." } ] }The same search with
Authorization: Bearer <token>:{ "products": [{ "id": "<product>", "price_range": { "min": <price>, "max": <price> }, "variants": [{ "id": "<product>:default", "price": { "amount": <minor units>, "currency": "<currency>" }, "quantity_unit": { "unit": "ANN", "display_text": "year" } }] }], "messages": [{ "type": "warning", "code": "nda_confidential", "presentation": "disclosure", "path": "$.products[0]", "content": "Confidential. Disclosed to <buyer email> under <seller>'s NDA. Not transferable." }] }A bad token:
Where eligibility lives
The B2B wholesaler example in identity linking describes eligibility, pricing, and payment terms as "user attributes the merchant resolves at runtime, not additional scopes." We followed that model for prices, which the business resolves on every priced call. The NDA step is the exception. It sits inside sign-in, and refresh tokens end when the NDA unlock ends.
Here, eligibility has three parts. They are a mailbox at a domain that is not free mail, an accepted NDA, and an optional approval by a person at the seller. The business checks all three without adding scopes or schema fields.
We did not use
continue_url, which the spec provides for accepting terms. It rides onidentity_required, which the spec ties to gated operations, and none of ours are gated.We also did not use
context.eligibility. Those claims come from the buyer and must not identify an individual. Because NDA eligibility belongs to a specific identified person, it comes through identity linking.Questions
identity_optionalthat signing in unlocks prices. It cannot see that sign-in needs a work email and an NDA, so it cannot tell the buyer in advance. A scope'sdescriptionwould be the natural place, but it lives only inconfig.scopes, which marks the scope gated. Is there an intended way to describe an optional scope? Or mayidentity_optionalcarry structured requirements as well as text?identity_requirednorinsufficient_scopefits. Should a standard message code for this come through [DTC Charter]: B2B Procurement #947, or is an extension-defined Action the intended home? Today we avoid the state by holding sign-in open until approval. That leaves a platform unable to tell a pending approval from an abandoned flow. [Proposal]: Quote extension — Business-authoritative quotation binding on Cart and Checkout #929 has a related gap forpendingquotes.identity_requiredonly for operations that a scope inconfig.scopesgates. It does not say what a business returns when an invalid token arrives on an operation no scope gates. One answer is a401witherror="invalid_token", as RFC 6750 suggests. That is what we do, reusingidentity_requiredfor an operation the spec does not gate. The other is to ignore the token and return the public response, so a buyer who believes they are signed in gets only a generic reason. Either can work, but platforms need one predictable answer. We would suggest: "When a request carries an invalid, expired or revoked access token, the business SHOULD respond with401,identity_required, anderror="invalid_token"in theWWW-Authenticatechallenge, even if no scope inconfig.scopesgates the operation. The platform can then refresh the token or retry without it." Would maintainers take this as a docs PR, or does it need a proposal?Cache-Control. Is such a response meant for that user only, on every transport and in a platform's memory? Does that include a colleague at the same company? If the first answer is yes, would maintainers take a one-sentence docs PR saying it?What we have not built
We are happy to share request and response traces, with tokens and addresses removed, or to test against a platform's sign-in flow.
All reactions