The sandbox

The sandbox is a complete second environment of MasterDB: its own key register, its own trust root and transparency log, and the same software as production. It serves a fictional corpus — businesses, AI companies and records of every type — published through the real publish path and sealed under sandbox certificates, so every sandbox record verifies with the production verifier and every response is real in shape.

	Sandbox	Production
API	https://sandbox.api.masterdb.ai	https://api.masterdb.ai
Verification API	https://sandbox.api.masterdb.ai	https://verify.masterdb.ai (and the same paths on api.masterdb.ai)
Trust anchors	the sandbox root, an explicit opt-in in every verifier	the production root, pinned
Log origin	masterdb.ai/log/sandbox/v1	masterdb.ai/log/v1

Every code sample on this site runs against the sandbox corpus.

What differs from production

Stated once, here:

• No verification. A sandbox key needs no verification of your company, and no AI-company Terms. A business’s sandbox integration key needs no verification either.
• Signed requests, as in production. Every sandbox request is signed with your key (Signing requests), and until the sandbox has seen your key, it carries the key’s grant (below).
• The same rate limits as production (Rate limits).
• Billing is computed and shown, never invoiced or paid out.
• Ads are served from fictional budgets, with real tokens and no money (ads and sponsored items).
• A sandbox: true member on every receipt and every certificate.
• Separate keys and roots. A sandbox key, certificate or signed token is never accepted by production: the issuer differs, and a request signature covers @authority, so a request signed for sandbox.api.masterdb.ai cannot be replayed to api.masterdb.ai.

Everything else is identical: envelopes, receipts, seals, AI policies, blocking, the projection specifications, error shapes, and the SDKs pointed at a different base URL.

Taking a sandbox key in the AI Portal

An AI company takes a sandbox retrieval key in the AI Portal, the same portal it uses for everything else; a business takes a sandbox integration key in the Business Portal. There is no separate sandbox portal or sign-in.

What the portal needs from you, for an AI company:

1. A person who may manage retrieval keys (owner, admin or integration_manager), signed in with a passkey.
2. Your company set up as an AI company in the portal.
3. The public half of your key, as a JWK, and a label.

It does not need your company to be verified, and it does not need the AI-company Terms.

The portal answers with the key’s id (the RFC 7638 thumbprint of the public JWK), sandbox_api_origin (where the sandbox API is) and a sandbox_key_grant (mdb_sbxk1.…): MasterDB’s signed statement of the key and your company, which holds no secret. The list of your sandbox keys returns the grant again. A revoked sandbox key stops working in the sandbox within about a minute.

Sending the grant: MDB-Sandbox-Key

The sandbox does not know your key until a request carries its grant. Send it as the MDB-Sandbox-Key header. The first signed request that carries it registers your company and the key in the sandbox, and is then verified like any other; without it, that first request is refused 401 key_unknown. The header is not part of the signature. A key revoked in the portal stays refused in the sandbox, with or without its grant. Production ignores the header, and a sandbox key is never registered in production.

POST /v1/search HTTP/1.1
Host: sandbox.api.masterdb.ai
Content-Type: application/json
MDB-Sandbox-Key: mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.…
Signature-Input: sig1=("@method" "@authority" "@path" "content-digest");created=…;keyid="…";tag="mdb-retrieval"
Signature: sig1=:…:

With the TypeScript SDK, pass the grant once and every request carries it:

const client = createRetrievalClient({ baseUrl: SANDBOX.retrieval, signer, sandboxKeyGrant });

createBusinessClient takes the same option for a business’s sandbox integration key. With the Python signing helper (Signing requests), pass it to the auth hook (the Python quickstart does):

client = httpx.Client(
    base_url=SANDBOX_API,
    auth=MasterDBAuth(load_key("retrieval-key.pem"), sandbox_key_grant=grant),
)

The CLI sends it on the signed fetch of masterdb verify --url:

masterdb verify --url https://sandbox.api.masterdb.ai/v1/records/mdb_… --sandbox-key-grant "$GRANT" --sign-key test-key.jwk --sandbox

The Postman collection has the header on its sandbox requests: set its value to your grant. The self-hosted MCP server takes it as sandbox_key_grant in its configuration (or MASTERDB_SANDBOX_KEY_GRANT) and sends it on every request; it is accepted only with "environment": "sandbox":

{ "version": 1, "environment": "sandbox", "key": { "file": "retrieval-key.jwk" }, "sandbox_key_grant": "mdb_sbxk1.…" }

The corpus

The corpus is generated from a fixed seed, so every reset reproduces it byte for byte and every identifier quoted in these documents exists. Names are unmistakably fictional (every legal name ends in “(Sandbox) Ltd” or “(Sandbox) Inc”), and every URL is on *.sandbox.masterdb.ai, so a link followed from a record lands somewhere harmless.

The corpus has deliberate variety: businesses in the US, Ireland, the UK, Canada and Australia across many verticals; catalogues published through both the portal and pushes; some businesses with purchase and reserve permitted and some with quote off; several Business & Brand files per country; and some businesses that block the sandbox AI company’s group, so that blocking can be tested from the AI side.

A few of the identifiers the guides use:

What	Identifier
Garnet Mill, a fictional Irish business that publishes through the portal	6c1658dd-fa53-4f12-8a18-6eee69f5ca99
One of its products	mdb_xmomas3i3kzkdwyqpfoxou5rea
Ember Spindle, a fictional business in the US and GB that pushes its catalogue	b809c8bd-8e0e-4a4b-92cb-e7f28cd36b01
Saffron Mill, which blocks the sandbox AI company’s group	0c148394-9635-498d-84bc-f4a785a948c5
The sandbox AI company, “MasterDB Sandbox AI (Sandbox) Inc”	fc8bb07a-86ab-4c08-8e0b-0b2fca555c44

Lifecycle

The corpus is republished nightly: the same ids and bytes, as new versions. What you create — your own sandbox business, keys, mandates, pushes, receipts — is kept for 90 days from its last use, with a notice 14 days before deletion.

Moving to production

Production is a separate path in the same portal, with its own key: your company is verified, accepts the AI-company Terms, and then registers a production key (Keys). Your sandbox keys stay and keep working in the sandbox, and are never accepted by production. A sandbox key is never turned into a production one. A business moves to production the same way from the Business Portal.