Skip to main content
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. 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 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

​
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 from Enrollment Flows. Hosted enrollment must be turned on for your organization (see Hosted Enrollment).
  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: 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. 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. 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.

​
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.
The KYA SDK is coming soon. The packages aren’t published yet, so the code below won’t run until they are.
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 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.
See the API reference. 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 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. 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