Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.

Test safely

Never use real customer data in development or tests, including “just one real ID to check it works”. Use a test vault and the made-up values below.

Test vaults

In Vaults → New vault, choose the environment Test, with made-up customers. Its ID starts v_test_, it comes with made-up customers to work with, and the console lets you try values on its fields (it never does on live vaults). It behaves exactly like a live vault: same checks, rules, audit and limits. Keep test and live strictly apart:

  • a separate service account and key for each test vault,
  • the vault ID in configuration (ONSHORE_VAULT), never hard-coded,
  • access rules copied from live with Copy setup so tests exercise the real rules.

Dry runs

tokenize with dryRun (dry_run in Python and the API) runs every check (format, access rules) and stores nothing. Use it to validate an import file, or in a health check that proves the service account works without writing data.

const results = await vault.tokenize(VAULT, rows, { dryRun: true, continueOnError: true });

Made-up values that pass format checks

These pass the vault’s format and check-digit validation. They’re for test vaults only. Some may happen to match a real person’s number; that’s harmless in a test vault holding no real data, but never use them anywhere real.

Data typeValue
uk_nino (UK National Insurance)AB123456C
uk_nhs943 476 5919
uk_bank_account (sort code and account)20-00-00 55779911
ibanGB82WEST12345698765432, DE89370400440532013000, AE070331234567890123456
eu_vatDE123456789, FR40303265045
de_tax_id86095742719
us_ssn123-45-6789
us_itin912-70-1234
us_routing011000015
ca_sin046 454 286
br_cpf529.982.247-25
in_aadhaar2341 2341 2346
in_panABCPE1234F
sg_nricS1234567D
za_id8001015009087
emirates_id784-1990-1234567-6
sa_national_id1012345672
eg_national_id29001010101230
ghana_cardGHA-123456789-0
ke_national_id12345678
ke_kra_pinA123456789B
emailsam@example.com (example.com is reserved for documentation)
phone+44 7700 900123 (UK numbers 07700 900000–900999 are reserved for drama)
date1988-03-14
person_nameSamuel Adeyemi

Card numbers are always refused by the vault. For card-detection tests, 4111 1111 1111 1111 is the well-known test card and is masked, never stored.

Values that must fail, for negative tests: GB00WEST12345698765432 (bad IBAN check digits), 943 476 5918 (bad NHS check digit), ABCDE1234F (not a valid PAN holder type).

Unit tests without a vault

Every server SDK can point at a fake server. The only endpoint the client needs is POST /v1/auth/token returning {"access_token":"t","expires_in":900}; script the rest for your test. Generate a throwaway key: any 32 random bytes, base64.

const fakeFetch: typeof fetch = async (url, init) => { const path = new URL(String(url)).pathname; if (path === "/v1/auth/token") return Response.json({ access_token: "t", expires_in: 900 }); if (path.endsWith("/tokenize")) { const { items } = JSON.parse(String(init!.body)); return Response.json({ results: items.map((_: unknown, index: number) => ({ index, token: `tok_test_${index}abcdefgh` })) }); } return Response.json({ error: { code: "invalid_request", message: "not scripted" } }, { status: 400 }); }; const vault = new VaultClient({ baseUrl: "https://vault.test", serviceAccountId: "sa", keyId: "k", privateKey: crypto.randomBytes(32).toString("base64"), fetch: fakeFetch, maxAttempts: 1 });

Test the paths that matter most, which are the failures: a denied decision, token_not_found after an erasure, validation_failed on bad input, and a thrown reveal (your code must show nothing).

CI

  • Store the test service account’s key as a CI secret; never in the repository.
  • Use a test vault per environment (CI, staging), or per developer for local work.
  • Run integration tests against the test vault on merges, and unit tests with a fake on every push.
  • Erase what tests create: tokenize with subject_ref: "ci-${runId}", then searchSubjects and eraseSubject in teardown.
afterAll(async () => { const { subjects } = await vault.searchSubjects(VAULT, { query: `ci-${process.env.GITHUB_RUN_ID}` }); for (const s of subjects) await vault.eraseSubject(VAULT, s.id, "CI teardown"); });

Trying the API by hand

The API reference has a built-in client. Get a bearer token first (sign an assertion as in Authentication), paste it into Authentication, set the server to your install, and send requests against a test vault.

Last updated on