Auth Gateway

Create an Altinn 3 System User delegation

Auth Gateway core flow. The consumer requests an Altinn System User to act on behalf of a Norwegian company (org_number) with a specific set of scopes. Altinn returns a delegation URL that the company's signing authority (signaturrett) must visit to approve. Until approval the delegation remains in 'pending' status; once approved it transitions to 'active' and the system user can be used to call Altinn on the organisation's behalf. The integration can run in live or sandbox/mock mode depending on the deployment's configuration. This operation is recorded in the append-only audit log.

post/api/v1/auth/system-user/delegate

Request

  • Base URL: https://www.apier.no
  • URL: https://www.apier.no/api/v1/auth/system-user/delegate
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional client-chosen key that makes this write safely retriable. When the same key is presented on a subsequent request with the same body, the gateway returns the original response (with Idempotent-Replay: true) instead of re-executing the write. Reservation is scoped to (consumer, endpoint, key) so the same key on different endpoints or different consumers does not collide. TTL: 24 hours. The key must be 1–255 printable ASCII characters — a v4 UUID or ULID is the recommended format. Keys are SHA-256 hashed before storage so they may safely carry client-internal identifiers.

X-Agent-Vendorstring

OPTIONAL forensic-only attestation: the agent vendor / framework that issued this request (e.g. anthropic, openai, langchain). Persisted to audit_log.agent_vendor and mcp_query_log.agent_vendor; never used for authorization, scope, rate-limit, or idempotency decisioning. The server strips ASCII control chars (0x00–0x1F + 0x7F), Unicode NEL / line / paragraph separators, and BOM before persistence; values exceeding 64 UTF-8 BYTES are byte-boundary clamped (a non-ASCII string declared at 64 chars may exceed the 64-byte ceiling and be clamped further). NEVER echoed in any response body, response header, _meta block, error message, or Sentry payload — one-way capture. Omitting this header writes SQL NULL to the persisted columns. The MCP transport equivalent is clientInfo.attestation.vendor.

X-Agent-Modelstring

OPTIONAL forensic-only attestation: the agent model id (e.g. claude-opus-4-7, gpt-4o-mini-2024-07-18). Persisted to audit_log.agent_model and mcp_query_log.agent_model; identical sanitisation + clamp + non-echo rules as X-Agent-Vendor (control-char strip, 128-UTF-8-BYTE ceiling, never visible on any response). Forensic-only: never used for authorization, scope, rate-limit, or idempotency decisioning.

X-Agent-Run-Idstring

OPTIONAL forensic-only attestation: an opaque agent-side run / trace identifier (e.g. a LangSmith run id, a vendor-specific session id). Persisted to audit_log.agent_run_id and mcp_query_log.agent_run_id; identical sanitisation + clamp + non-echo rules as X-Agent-Vendor (control-char strip, 256-UTF-8-BYTE ceiling, never visible on any response). Forensic-only: never used for authorization, scope, rate-limit, or idempotency decisioning.

Request body

org_numberstring required

Norwegian organisation number. Exactly 9 digits, matching Brønnøysund Register Centre format. Any other shape returns 400 VALIDATION_FAILED before the upstream call is made.

scopesstring[] required

Altinn scopes to request (e.g. 'altinn:accessmanagement/authorizedparties.read'). At least one scope is required. The scope list appears verbatim on the approval page shown to the signing authority, so request only what the integration actually needs.

validity_daysinteger

Desired delegation validity window in days. Optional — if omitted, Altinn applies its own default cap. Upper bound of 10 years matches Altinn's longest supported delegation term.

labelstring

Consumer-supplied label shown in the dashboard to distinguish multiple delegations for the same org/consumer pair. Never forwarded to Altinn.

system_user_type'standard' | 'client_delegated'

Kind of Altinn system user to request. 'standard' acts for the one organisation that approves it. 'client_delegated' is Altinn's agent system user, which an accounting firm or platform uses to act for its clients through client delegation (klientdelegering); a company that reports for itself and for clients needs one of each. Optional: omitting it requests a standard system user, exactly as before the field existed. Any other value returns 400 VALIDATION_FAILED. In live mode only 'standard' can be requested today; 'client_delegated' returns 503 ALTINN_NOT_CONFIGURED before any call to Altinn, and works in mock mode.

Example request

{
  "org_number": "999999999",
  "scopes": [
    "altinn:accessmanagement/authorizedparties.read"
  ],
  "validity_days": 365,
  "label": "Production integration — Oslo HQ",
  "system_user_type": "standard"
}

Response

Delegation created. Until the org's signing authority approves the delegation_url, status remains 'pending' and the system user cannot yet be used to call Altinn on the org's behalf.

successtrue required

Example response

{
  "data": {
    "system_user_id": "altinn-su-12345"
  },
  "_meta": {
    "rulebook_version": "v1.0.0",
    "source": "apier.no",
    "data_source": "Brønnøysund Enhetsregisteret + Apier Universal Rulebook",
    "schema_version": "1.0.0",
    "legal_basis": "NLOD — public registry reuse",
    "response_timestamp": "2026-04-24T12:00:00.000Z",
    "response_hash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "source_snapshot_id": "brreg-2026-04-24T02:00:00.000Z",
    "cost_nok": 0.5,
    "wallet_remaining_nok": 9.5,
    "spend_cap_remaining_nok": 12.5
  }
}

Changes

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