Skip to main content

Sandbox

Availability

Sandbox mode is GA on production as of v0.99.6.1. You test with a sandbox key (pk_test_*) against the same base URLs as live — no separate environment or access request needed.

There are two ways to try the Integration API without touching real data.

Every key is either live (pk_live_*) or sandbox (pk_test_*). A sandbox key runs the exact same API on the same base URL, but its writes create throwaway data that is never linked to a real published passport, and it has its own rate-limit quota.

  • Mint a pk_test_ key in Settings → API Keys.
  • Send X-Traceable-Mode: test on every request. If the header is missing or wrong, the request fails loud with 400 MODE_HEADER_MISMATCH — it never silently writes to the wrong place.
  • The GDPR endpoints are live only; a sandbox key there returns 403 CROSS_MODE_DENIED.

See Authentication → Sandbox mode.

When you are ready for real passports, mint a pk_live_ key and drop the X-Traceable-Mode header. The mode is the key, not the base URL, so nothing else changes.

All sandbox testing runs against the production base URL with a pk_test_ key — there is no separate public pre-release environment to point your integration at.

What testing is good for​

  • Validating your field mapping against the Annex XIII gate
  • Testing error handling (lock conflicts, signature errors, SUBMIT_BLOCKED)
  • Confirming your HMAC signing implementation before going live
  • CI/CD integration testing

Not a mock​

Sandbox mode is not a stub. It runs the same API code as live, including real HMAC signature verification, idempotency enforcement, Annex XIII gate evaluation, and document magic-byte validation. If your integration passes in sandbox mode, it behaves the same way live (subject to rate limits and plan entitlements).