Skip to content
Apier

Knowledge Catalog

Testing against the Apier sandbox

The Apier sandbox mirrors the production API surface under /api/v1/sandbox/* using synthetic fixtures only — it never makes a network call to any government upstream, so a sandbox 'filing' is a local state transition and nothing binding ever leaves the system. Every sandbox response carries _meta.is_sandbox: true.

Jurisdiction: Norway · Verified against Apier (synthetic sandbox surface) as of 2026-07-18

What the sandbox guarantees

Sandbox responses are served entirely from in-code synthetic fixtures and ephemeral session state. No real credentials are exchanged: the sandbox auth mirror accepts Bearer tokens of the form apier_sandbox_test_<suffix> and bypasses the live key lookup entirely, and no Maskinporten or Altinn credential is ever spent. Responses are deterministic — same input, same fixture version, same output.

Synthetic companies and personas

Fixture companies use reserved MOD-11-valid organisation numbers (the 999… range; 999999999 is the docs-standard example). Beyond the happy-path fixtures, eleven difficult-company personas in the 999770-series model realistic hard cases — bankruptcy in progress, voluntary liquidation, VAT-deregistered, disputed signature rights, degraded data, merger-absorbed, NUF branch, dormant, and more — each internally consistent across verify, roles, VAT, accounts, obligations, and deadlines.

Failure simulation

Sandbox endpoints support a ?simulate_error= query parameter with the values missing_delegation, invalid_token, validation_error, and scope_missing. Simulated errors are produced locally and return production-shaped error bodies using the same Compliance Explainer format as production, so an agent can rehearse its error handling without triggering a real failure. Latency simulation is likewise local and deterministic.

Rehearsing the write loop

The sandbox rehearsal endpoint lets an agent run the full MVA write loop — dry-run, approval token, submit — against the fixture surface. The submit is a local state transition only; no real submission ever leaves the system, which is what makes the sandbox safe for public, keyless experimentation.

Use cases

  • Develop and test an agent integration end-to-end before holding a live API key
  • Rehearse error handling by inducing production-shaped failures deterministically
  • Exercise hard company states (bankruptcy, liquidation, disputed signatur) that are rare in live data
  • Demo a filing flow with zero risk of a binding government write

Requirements

  • A sandbox bearer token of the form apier_sandbox_test_<suffix> for the authenticated mirror (no registration needed)
  • Nothing at all for the zero-auth public sandbox mirror

Authentication

Method: none

The public sandbox mirror is zero-auth; the authenticated mirror accepts any apier_sandbox_test_<suffix> bearer without a live key lookup. No production credential is ever required or accepted on the sandbox path.

Common errors

  • VALIDATION_FAILED

    Returned genuinely for malformed input — or on demand via ?simulate_error=validation_error.

    Fix: Fix the input; or if simulating, this is the expected rehearsal outcome.

  • SANDBOX_TOOL_UNAVAILABLE

    The MCP tool called under a sandbox bearer has no sandbox mirror route.

    Fix: Use one of the sandbox-mirrored tools/routes, or switch to a live API key for tools without a mirror.

Related topics

Related APIs

Capability ids — resolve each against the machine-readable manifest at /api/v1/capabilities for the endpoint, auth mode, and tier.

  • actions.execute_dry_run
  • sandboxCompanyVerify
  • sandboxCompanyObligations
  • rehearseMvaWriteLoop

Related MCP tools

Registered tools on the Apier MCP server.

  • submit_vat_return
  • validate_action