> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Let Shopping Agents Check Out

> How a merchant lets verified agents shop, sign in and check out, and recognizes the customer behind each one.

## 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

> [!NOTE]
>
> 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](https://docs.baselayer.com/docs/credential-format-reference.md).

**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

| Party | What they see |
| - | - |
| Merchant | A stable customer ID for its site, the shared fields for that scope, the checks that passed when Baselayer verified the person (such as phone confirmed or watchlists clear) and the expiry. Or a typed failure reason. |
| Agent | A single-use nonce, then the merchant's own session token if the credential is accepted. |
| Person | No additional step on a return visit when the agent already has a valid credential. The credential can include only fields listed in the merchant's KYA profile. |
| Baselayer | Requests for its public signing keys and the shared revocation list, both cached. These don't identify which customer is being checked. |

## What adopting takes

* Publish a KYA profile. See [Asking for Fields](https://docs.baselayer.com/docs/kya-asking-for-fields.md).
* 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](https://docs.baselayer.com/docs/kya-sdk-quickstart.md) 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](https://docs.baselayer.com/docs/kya-matching-customers.md).

## Recommended settings

| Setting | Recommendation |
| - | - |
| `audience` | The merchant's domain, exactly as credentials are minted for it. The site is matched exactly: `shop.example` and `www.shop.example` are two different sites with two different IDs. |
| Scopes | One per step. List only the field paths that step needs. A credential that shares more is refused with `SCOPE_VIOLATION`. |
| Customer lookup | Key customers on `claims.sub` in the merchant's own database. The verifier keeps no record of who it has seen. Never key on `jti`. |
| Account linking | Treat an email hash match as a lead, not proof. Confirm ownership before granting account access. |
| Session length | Never let a session outlive `claims.exp`. |
| Nonce store | Required. `InMemoryNonceStore` works for one long-lived process. On more than one server, give every instance the same `NonceStore`, backed by Redis or a database. |
| Verifier | Create one per process and reuse it. It holds the key and revocation list caches. |
| Sandbox | Leave `allowSandbox` off in production. Turn it on only in testing. |
| Outages | Decide ahead of time whether to fail open (treat the agent as an unverified visitor) or closed (return `503`) on `ISSUER_RESOLUTION_FAILED` and `STATUS_LIST_RESOLUTION_FAILED`. |

## Next steps

* Understand the recipient flow and set it up: [Accepting Agents at Your Site](https://docs.baselayer.com/docs/kya-accepting-agents.md)
* Publish your profile: [Asking for Fields](https://docs.baselayer.com/docs/kya-asking-for-fields.md)
* Test before production: [KYA Sandbox and Testing](https://docs.baselayer.com/docs/kya-sandbox-and-testing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.