Sandbox

Sandbox plan describing the prerequisite chain (API key or sandbox bearer)

Returns the deterministic prerequisite chain for executing a regulatory action. Plan describes 5 steps in order: verify_company → verify_delegation → validate_payload → mint_approval_token → execute. Sandbox plan is its own contract — there is NO production /api/v1/actions/plan endpoint to mirror today. introduced this surface so 's full chain can run end-to-end on sandbox.

Plan does NOT emit the approval token directly — call /api/v1/sandbox/auth/approval-token after plan. The plan response includes mint_endpoint (the URL to call next) and requires_approval (boolean). These field names deliberately AVOID the substring token because the integration suite's secret-scanner walks every response key against /token|secret|password|key_hash|api_key/i — using requires_approval_token / approval_token_endpoint would have triggered false positives on a deterministic metadata field.

post/api/v1/sandbox/actions/plan

Request

  • Base URL: https://www.apier.no
  • URL: https://www.apier.no/api/v1/sandbox/actions/plan
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Query parameters

simulate_error'missing_delegation' | 'invalid_token' | 'validation_error' | 'scope_missing' | 'altinn_timeout' | 'invalid_certificate' | 'malformed_payload' | 'upstream_5xx' | 'AUTH_MISSING_DELEGATION' | 'AUTH_EXPIRED_TOKEN' | 'VALIDATION_FAILED' | 'SCOPE_MISSING'

Force the sandbox to return a structured error response. tokens (Apier-edge failures) — missing_delegation → 403 AUTH_MISSING_DELEGATION; invalid_token → 401 AUTH_EXPIRED_TOKEN; validation_error → 400 VALIDATION_FAILED; scope_missing → 403 SCOPE_MISSING. upstream-failure tokens — altinn_timeout → 504 EXECUTION_DEADLINE_EXCEEDED (Altinn 3 instances endpoint timed out, response body carries the Altinn RFC 7807 envelope); invalid_certificate → 502 MASKINPORTEN_AUTH_FAILED (Maskinporten OAuth2 error_object — invalid_client); malformed_payload → 422 GOVERNMENT_VALIDATION_REJECTED (Skatteetaten validation errors with nested path[] arrays); upstream_5xx → 502 GOVERNMENT_UNAVAILABLE (generic government 5xx). The 500 INTERNAL_ERROR path is reserved for unexpected internal failures. Accepts BOTH lowercase public tokens (primary contract) AND uppercase internal explainer codes (back-compat). Wins precedence over reserved-org defaults.

Headers

Idempotency-Keystring

Accepted for cross-client header parity with production but NOT enforced — sandbox plan is a deterministic shape; the same body produces the same plan on every call. Charset / length validated at the boundary.

X-Correlation-IDstring uuid

Optional request-scope UUID v4 that the client can set to thread its own trace across multiple requests. A valid UUID v4 is reused verbatim on the server; anything malformed or absent is replaced with a fresh crypto.randomUUID(). The canonical value is echoed back on the X-Correlation-ID response header AND persisted on every matching audit_log row — so a forensic query can reconstruct "every row from request X" without timestamp-based correlation. Accepted on every /api/v1/* operation via the proxy middleware; no per-operation opt-in required. The header is also emitted on every /api/v1/* response — see the X-Correlation-ID response-header component.

Request body

org_numberstring required

9-digit reserved synthetic org. Must appear in the data.sandbox.reserved_test_org_numbers array on the response body of GET /api/v1/capabilities (or 999000901-904 for reserved error orgs). Any other 9-digit value returns 400 VALIDATION_FAILED — distinct from the read-side which 404s on unknown orgs (sandbox write-side invariant).

action'mva_melding' | 'a_melding' required

Response

Plan returned. Each step has step (machine-readable id), status (ok for prerequisites already satisfied, pending for what the agent must do next), and description_nb (Norwegian bokmål prose).

successunknown required

Changes

No recorded changes to this operation across all 1 revision of this API.