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

# KYA Sandbox and Testing

> Test the full KYA flow with test data before you touch production.

Use this page when you're ready to test a KYA integration before going to production. It covers how to run a full test with test people and businesses, how your test site accepts sandbox credentials, and how sandbox data stays separate.

If you only want to see what a person sees when they verify, start with the [Hosted Enrollment Playground](https://docs.baselayer.com/hosted-enrollment/playground.md).

KYA follows the same rule as the rest of Baselayer: the API key you call with decides the environment.

* A sandbox key works in your sandbox application, and a production key works in your production application.
* The endpoints and request shapes are the same.

See [Sandbox vs. Production Environments](https://docs.baselayer.com/docs/sandbox-vs-production-environments.md) for keys and the console environment selector.

What is different for KYA is that the two environments never mix, and that sandbox credentials are signed by a different issuer.

## Choose a testing path

| What you want to test | What you need |
| - | - |
| Test the full flow with test people and businesses | A sandbox application and sandbox API key. See [Run a full sandbox test](#run-a-full-sandbox-test). |
| Test a production person at a staging site without minting a production credential | The test credential endpoint with a production API key. See [Test a production identity without minting a production credential](#test-a-production-identity-without-minting-a-production-credential). |

## Run a full sandbox test

A full sandbox test has four steps: verify the test person and business, mint a credential, present it to your test site, and check it there. All of it uses your sandbox application and a sandbox API key.

### 1. Verify the test person and business

Sandbox has no shortcut that creates a test person. You create one the same way as in production: someone completes your hosted enrollment flow while your sandbox application is selected. In sandbox, the person check runs against test data and the business check answers from Baselayer's seeded sandbox businesses, so enter the values below exactly.

To enroll the test person:

1. In the console, select Sandbox, then open your [enrollment flow](https://docs.baselayer.com/hosted-enrollment/journeys.md) from Enrollment Flows. Hosted enrollment must be turned on for your organization (see [Hosted Enrollment](https://docs.baselayer.com/hosted-enrollment/overview.md)).
2. Leave the country as United States, then enter the phone number `+1 210-555-8890` and the date of birth `1997-03-11`.
3. At the code step, enter any six digits except `000000` (for example `123456`).
4. Confirm the details shown. The person is verified.

To add the test business in the same flow:

| Field | Value |
| - | - |
| Legal name | `Joe's Burger Shack LLC` |
| EIN | `831234567` |
| Address | `2345 Main Street, Houston, TX 77002` |

The test business is an active Texas LLC. Its business check comes back verified with a matching tax ID and no watchlist hits, so the test person's link to it is `VERIFIED` without a manual review, and you can mint business credentials for the pair right away. See [Who Can Act for a Business](https://docs.baselayer.com/docs/kya-who-can-act-for-a-business.md).

Once enrolled, the test person appears under People and the test business under Businesses, only while Sandbox is selected. Use their `individual_ref` and `business_ref` in the next step.

### 2. Mint a credential

Mint with your sandbox key, using the test person's `individual_ref` (and `business_ref` for a business credential). The request is the same as in production. See [Minting Credentials](https://docs.baselayer.com/docs/minting-credentials.md). The credential is signed by the sandbox issuer.

### 3. Present it to your test site

Present the credential to your test site the same way an agent would in production. Your test site must accept sandbox credentials. See [Let your test site accept sandbox credentials](#let-your-test-site-accept-sandbox-credentials).

### 4. Check it

The test site checks the credential the same way as in production. A sandbox credential passes only when the site accepts sandbox credentials.

## Let your test site accept sandbox credentials

Sandbox credentials are test data, so the KYA SDK refuses them by default. The refusal comes before any network call, with the code `SANDBOX_ISSUER`.

To accept them, for example in your own staging site, turn on the sandbox switch when you create the verifier.

> [!NOTE]
>
> The KYA SDK is coming soon. The packages aren't published yet, so the code below won't run until they are.

```ts TypeScript theme={null}
import { InMemoryNonceStore, KyaVerifier } from "@baselayer/kya";

const verifier = new KyaVerifier({
  audience: "shop.example",
  nonceStore: new InMemoryNonceStore(), // one process only; see Where to Run the Check
  allowSandbox: true,
});
```

```python Python theme={null}
from baselayer_kya import InMemoryNonceStore, KyaVerifier

verifier = KyaVerifier(
    audience="shop.example",
    nonce_store=InMemoryNonceStore(),  # one process only; see Where to Run the Check
    allow_sandbox=True,
)
```

With the switch on, the verifier trusts both issuers. Leave it off in production. A business presentation must use one issuer for both of its credentials, so a sandbox credential can never be paired with a production one.

If you verify without the SDK, trust the sandbox issuer only in test environments, and fetch its keys and status lists from the sandbox host, never from production.

### Testing as a site

A site that only accepts credentials needs a sandbox credential minted for its own audience. If you have a Baselayer sandbox application, run the [full sandbox test](#run-a-full-sandbox-test) yourself with your test site's domain as the `audience`. If you don't, ask the agent platform you work with to mint one for your test site's domain with its sandbox key.

## How sandbox and production stay separate

Every KYA record belongs to the application it was created in: people, businesses, operator links, issued credentials and audit log entries.

* People and businesses you verify with a sandbox key appear only in sandbox lists and lookups. Production lists never return them.
* An `individual_ref` or `business_ref` from your sandbox application returns `404` when you look it up with a production key, and the other way around. It reads exactly like a reference that does not exist. One exception: once you mint a test credential for a production person or business, the credential list and audit log filters accept that production reference with a sandbox key.
* Credentials you mint in sandbox show up only in your sandbox `GET /issuance/credentials` list, and can only be revoked with a sandbox key.
* Your sandbox is yours. If another organization enrolls the same test person, theirs is a separate person with separate references, and neither organization can see the other's.

## Test a production identity without minting a production credential

Use this when you want to test a production person or business at a staging site.

```http theme={null}
POST /issuance/credentials/test
```

See the [API reference](https://docs.baselayer.com/api-reference/credentials/mint-a-test-credential-for-a-person-or-a-business-operator.md).

This endpoint takes the same body as `POST /issuance/credentials` and mints the same credential, signed by the sandbox issuer. It works with a production key too, for a person or business verified in production, so you can test a real person's credential at a site's staging environment without minting a production credential. [`POST /issuance/credentials/test/preview`](https://docs.baselayer.com/api-reference/credentials/preview-what-an-l3-test-mint-would-disclose) previews it.

* The test credential is recorded in your sandbox application, so it appears in your sandbox credential list.
* Its `sub` is its own per-site ID, never the one a production mint gives the same person at the same site.
* Sites accept it only when they accept sandbox credentials.
* It needs an `Idempotency-Key`, like a production mint, and your organization needs a sandbox application.

## Sandbox issuer reference

Credentials minted with a sandbox key are signed by Baselayer's sandbox issuer, with its own signing key and its own revocation status list.

| | Production | Sandbox |
| - | - | - |
| Issuer (`iss`) | `https://registry.baselayer.com` | `https://sandbox.registry.baselayer.com` |
| Signing keys | `https://registry.baselayer.com/.well-known/jwt-vc-issuer` | `https://sandbox.registry.baselayer.com/.well-known/jwt-vc-issuer` |
| Status lists | `https://registry.baselayer.com/statuslists/{list_id}` | `https://sandbox.registry.baselayer.com/statuslists/{list_id}` |

Everything else in a sandbox credential is shaped exactly like production, including its `vct` (credential type) URL, which names the production registry for both. Revoking a sandbox credential only touches the sandbox status list.

## Troubleshooting

| Problem | Fix |
| - | - |
| A reference you just created returns `404` | Check that you are using a key from the same application (sandbox or production) the person was verified in. |
| The site refuses your credential with `SANDBOX_ISSUER` | You minted with a sandbox key. Mint with a production key, or have the site's test environment turn on `allowSandbox` / `allow_sandbox`. |
| You cannot mint because your sandbox has no people | Enroll the test person through your hosted enrollment flow with Sandbox selected. |


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