Skip to main content

​
Overview

Shopping agents arrive at a merchant’s site on behalf of real customers, but they usually look like anonymous bots. The merchant can’t tell who the agent represents, connect the visit to an existing account, or apply the customer’s loyalty status and order history. Key challenges for merchants:
  • Distinguishing an agent acting for a verified person from an anonymous bot
  • Recognizing the same customer when their agent returns
  • Connecting the agent to the customer’s existing account
  • Getting the details needed at checkout without collecting more than required
  • Supporting verified agents without disrupting checkout for everyone else
With KYA, an agent presents a credential that identifies the person it represents. The merchant checks it in its own code and receives a stable, site-specific customer ID, the verification checks that passed, and any available fields listed in its KYA profile. The merchant then decides what the agent may do.

​
What happens when an agent arrives

Parts of this playbook use the KYA SDK, which is coming soon. Those steps won’t work until the packages are published. Until then, you can check credentials yourself with the Credential Format Reference.
1

The merchant asks for proof

A protected page returns 401 with a KYA-Disclosure-Scope header naming the KYA profile scope required for that step.
2

The agent gets a credential

The agent reads the merchant’s KYA profile and gets a credential with no more than the fields that scope allows.
3

The agent presents it

The agent gets a one-time nonce and sends the signed presentation to the merchant’s token endpoint.
4

The merchant checks it

The KYA SDK checks the credential, the agent’s signature, the audience, the nonce, the expiry, the revocation status and the disclosure scope.
5

The merchant decides

The merchant connects the site-specific ID to its customer records and applies its own rules. For example, it can let any verified customer browse and require specific checks before checkout, such as a clear watchlist result. It returns an access token when appropriate.

​
What each party sees

​
What adopting takes

  • Publish a KYA profile. See Asking for Fields.
  • Add a nonce route and a token route.
  • Check credentials with the KYA SDK.
  • Store the site-specific customer ID with customer accounts.
  • Decide which actions require which proof.
  • Start in watch-only mode, verifying and logging every credential, before changing anyone’s access.
The KYA SDK Quickstart has the code for each step.

​
Recognizing returning customers

Each merchant receives a stable, site-specific ID for the person.
  • When an agent returns with another KYA credential for that merchant, the ID is the same across agents and sessions.
  • The merchant can store it with the customer’s account and use it for loyalty, order history and cart recovery.
  • A different merchant receives a different ID for the same person.
See Matching Customers.

​
Next steps