An agent that signs a shopper in at a store has to answer one question: which of the store's accounts is this person? On 31 October the UCP spec merged PR #998, which lets a store answer it by email address, but only when the identity provider vouching for that address is the one that runs the mailbox. Gmail addresses vouched for by Google, yes; the same address vouched for by any other sign-in service, no.
The rule is on the spec's main branch and planned for the 2026-12-08 release, a plan that can move. It sits inside UCP identity linking's Accelerated IdP Flow, which is already in release 2026-08-25. We built both sides: two test identity providers and a store in UCP Sandbox, and the platform side in UCP Playground. Then we linked the same shopper three ways. Every request, reply and screenshot below comes from those sessions.
What is email matching in UCP identity linking?
Email matching lets a store link a signed-in shopper to an existing account by email, when the identity provider that issued the shopper's grant is the mailbox authority for that email's domain. Everywhere else the store links by the provider's own user id, (iss, sub), and does not merge accounts by email. In the spec's words:
Businesses MAY resolve a grant to an existing account by matching
The conditions, all of which must hold:
- The store has independently established that the issuer runs mail for the email's domain (for example, a consumer mailbox provider's own domain). The grant cannot claim this for itself.
- The grant asserts
email_verifiedas the JSON booleantrue. - The existing account's address was verified by the store itself, not imported from another provider's claim.
- Nothing is already linked the other way: the account isn't linked to a different
subfrom the same issuer, and the grant's(iss, sub)isn't linked to a different account.
Once linked, the store MUST resolve that account by (iss, sub) and MUST NOT move the link if the email changes later. It SHOULD tell the account holder that a link was made.
Why the rule is narrow
Before #998, the spec said stores SHOULD NOT auto-link accounts across identity providers by email at all. Any provider can put any address in a token. If a store trusted that, a careless or hostile provider could say "this is [email protected]" and take over Alice's account. A mailbox provider is different: it owns the inbox, so its word on that address is the strongest there is.
The risk that remains is named in the spec: providers that recycle or reassign addresses. Whether a given domain is safe is left to each store to judge.
What changed
| Before #998 | After #998 (main) | |
|---|---|---|
| Grant from a provider that runs the mailbox, existing account with that email | Don't auto-link; ask the shopper to sign in to the account | May link by email, if all four conditions hold |
| Grant from any other provider, existing account with that email | Don't auto-link | Don't auto-link (unchanged) |
Grant whose (iss, sub) is already linked |
Resolve by (iss, sub) |
Resolve by (iss, sub) (unchanged) |
It came out of review on #876, a wider proposal that lets a provider prove authority through DNS delegation; #876 is still open. #998 is the simpler first-party case that needs no new DNS records or identity-provider features. Three reviewers approved it, and it merged on 31 October.
How the flow works (Accelerated IdP Flow)
Email matching is one decision inside a flow that already exists in release 2026-08-25:
- The store lists the identity providers it trusts in its UCP profile, under
config.providersindev.ucp.common.identity_linking. - The platform signs the shopper in at one of them, once.
- For each store, the platform swaps that sign-in for a JWT authorization grant at the provider (token exchange, RFC 8693): short-lived, aimed at that one store (
aud), with a uniquejti. - The platform presents the grant at the store's token endpoint (
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, RFC 7523). - The store checks it (issuer on its list, signature against the provider's keys, audience, lifetime,
jtinot seen before), works out the account, and issues its own access token.
Step 5's "works out the account" is where #998 applies.
The setup
Three hosts in UCP Sandbox, built for this guide:
- Sandbox Mail, a mock mailbox provider. Every account is a mailbox on its own domain, so it is the mailbox authority for that domain. Our test shopper is Alex Rivera.
- Sandbox ID, a general sign-in service. It signs in any address you type and says it's verified, but it runs no mailboxes.
flowers-chain, a flower store that trusts both providers. It already has an account for Alex, with an address the store verified itself and two past orders.
The store's list of mailbox authorities is its own setting ("Sandbox Mail runs mail for this domain"), never read from a token. The platform is UCP Playground's Inspect, which sends each call by hand and keeps every request and reply in the trace on the right.
Step 1: The store offers sign-in through two providers

The store's UCP profile lists both providers in config.providers, so Inspect offers a "Link via" button for each, beside the store's own sign-in.
Step 2: Link through the mailbox provider
Alex signs in at Sandbox Mail once ("Continue as Alex Rivera"). Playground then exchanges that sign-in for a grant aimed at the store. The trace shows the grant decoded:

Step 3: The store matches Alex's existing account by email

All four conditions hold: the issuer is the mailbox authority for the address, email_verified is true, the store verified Alex's address itself, and no other link exists. So the store links the grant to Alex's existing account instead of creating a new one. (The Ucp-Sandbox-Decision header is a sandbox aid so you can see which rule fired; it isn't part of UCP.)
Step 4: The proof: Alex's order history

Reading an order needs a linked account on this store. With the token from Step 3, get_order returns Alex's past order. That's the practical point of the rule: the shopper keeps their history instead of starting a second, empty account.
Step 5: The same email through a provider that doesn't run the mailbox
Now Alex links through Sandbox ID with the same address. The grant looks almost the same, but the issuer is different:

The store refuses with invalid_grant, as the spec says to when user interaction is needed, and nothing is linked. Inspect points to linking directly at the store instead:

Step 6: After an email change, the link still holds
Alex changes their email at the store, then links again through Sandbox Mail. The grant still carries the old address, but that no longer matters:

The store found the account by (iss, sub) from the first link, as the spec requires. The store's account page keeps the notice it sent Alex and its log of decisions:


Which identity providers can use it
Only one that runs the mailboxes for the address's domain: a consumer mail provider for its own domain, or a company's own provider for its staff domain. A general sign-in service can't, however good its verification. Across the stores we check, most Shopify stores list Shop (app.shop.accounts) as their identity provider. Shop is a sign-in service, not a mailbox provider, so its grants link by (iss, sub) as before, and #998 doesn't change that.
What it means for stores
- Keep a list of the mailbox authorities you trust, per domain. The grant can't tell you; the spec makes it your decision, including whether a provider recycles addresses.
- Only match against addresses you verified yourself. An address imported from another provider's claim doesn't qualify.
- Tell the account holder when a link is made by email, and resolve by
(iss, sub)from then on.
What it means for agent builders
- Request
emailandemail_verifiedfrom the provider. Without them the store can only provision a new account or refuse. - Treat
invalid_grantas "the shopper must sign in at the store". Fall back to the store's own account linking; don't retry the grant. - One provider sign-in can serve many stores. Each store gets its own short-lived grant.
What we'll watch
The 2026-12-08 release, and whether #876's DNS-delegation route follows. Once it ships, we'll look at which stores list identity providers in config.providers, and which of those providers run mailboxes. Every open proposal and recent merge is on our Changes to UCP tracker.
FAQ
What does "mailbox authority" mean in UCP?
The identity provider that runs the mailboxes for an email domain, for example a consumer mail provider for its own domain. Its word that an address is verified is the strongest there is, because it owns the inbox.
Can any identity provider link me to my existing store account by email?
No. Only a provider the store has established is the mailbox authority for your address's domain, and only if your address on the store was verified by the store itself. Otherwise you sign in to the existing account to link it.
Which UCP release has email matching?
It's on the spec's main branch, merged on 31 October 2026, and planned for the 2026-12-08 release, a plan that can move. The flow it sits in, the Accelerated IdP Flow, is in release 2026-08-25.
What happens if my email changes after linking?
Nothing changes for the link. After the first match the store must resolve your account by the provider's user id, (iss, sub), and must not move the link to follow your email.
What does a store return when it won't match by email?
invalid_grant, meaning user interaction is required. The platform should then send the shopper through the store's own account linking.
Is this the same as #876?
No. #876 proposes letting a provider prove authority through DNS delegation and is still open. #998 is the narrower case where the store already knows which provider runs the mailbox.
How can I try it?
Open flowers-chain in UCP Playground's Inspect and use "Link via" on each provider.
About UCP Checker
UCP Checker is the independent validation and observability layer for the Universal Commerce Protocol. We crawl, validate and grade every public UCP manifest we can find, run the merchant directory, the UCP Score, live adoption stats, the vertical guides and the authority-bound vendor map, and track the spec as it evolves so you don't have to — measured from two vantages (what a business declares, and what actually happens when an agent transacts), the same way for everyone, without picking winners.
Sources
- Identity Linking. UCP specification, main branch: Accelerated IdP Flow, Business Token Issuance, Security Considerations.
- PR #998: permit email matching when the issuer is the mailbox authority. Merged 31 October 2026.
- PR #876: allow email matching when the IdP is the DNS-delegated authoritative email issuer. Open.
- Milestone 2026-12-08. UCP spec repo, a plan that can move.
- RFC 8693: OAuth 2.0 Token Exchange. IETF.
- RFC 7523: JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants. IETF.
Related coverage: UCP identity linking in agentic commerce · UCP agent profiles and verifiable identity · UCP Subscriptions explained, step by step · How UCP's Ask works, step by step
