Skip to content
Apier

Knowledge Catalog

Altinn 3 System Users

An Altinn 3 System User is a non-human actor an organization registers in Altinn so that other organizations can grant it rights. It authenticates with a Maskinporten access token issued for the integrating organization; authority comes from a delegation the target organization explicitly granted in advance, with no human identity in the loop at request time.

Jurisdiction: Norway · Verified against Digitaliseringsdirektoratet / Altinn as of 2026-05-09

The two delegation models

There are two ways an actor can perform an Altinn action on behalf of an organization. A personal user signs in with BankID or ID-porten and acts under that human's authority — the default for one-off filing flows. A System User is a registered non-human actor: the integrating organization authenticates via Maskinporten, and authority comes from a delegation the target organization granted in advance. The models are complementary; recurring, programmatic, no-human-in-loop work only becomes reliable with a System User behind it.

Why System Users exist

The personal-user model breaks down at scale: it requires per-action human authentication, ties every action to that human's continued employment, and leaks personal identity into machine-to-machine traffic. The System User model decouples the integrating party from the human chain — once the target company has granted rights, automation can act on them without re-authenticating a human, the audit trail records which System User acted, and the target company can revoke the delegation at any time.

The three-leg setup

Standing up a System User requires three independent pieces of infrastructure, none optional. Leg 1: a Maskinporten OAuth2 client registered for the integrating organization, bound to a virksomhetssertifikat (from Buypass or Commfides) plus a JWK upload. Leg 2: Samarbeidsportalen onboarding — signing Digdir's bruksvilkår (terms of use), a one-time legal-administrative step performed by someone with signature authority. Leg 3: an Altinn System Register registration plus a per-target delegation — each target company must add the System User in its own Altinn portal and grant specific rights to it. The legs interlock: a working client without onboarding cannot reach the live API; a live client without a System User registration cannot act on behalf of anyone; a registration without a per-target delegation cannot act for that specific company.

Limitations

System Users are not a universal substitute for a personal user. Step-up actions that require a human signing event (BankID-level identity assertion at action time) are refused at the Altinn layer regardless of configuration. Delegations can be revoked at any time, so cached permission state goes stale instantly — re-verify before acting on a delegation older than a few minutes. Maskinporten token lifetime is short (on the order of minutes; 120 seconds is the canonical test-environment figure), so tokens must be cached in memory and refreshed on demand, never persisted. Finally, a System User that exists but has no rights granted authenticates successfully yet cannot act — treat presence and permissions as two separate questions.

How Apier wires this together

Apier's Auth Gateway holds the Maskinporten client, performs the Altinn round-trip, and writes an audit row. POST /api/v1/auth/system-user/delegate orchestrates the delegation flow for a target organization; GET /api/v1/auth/permissions/{org} returns the current authoritative permission set sourced directly from Altinn at request time. The agent presents only an Apier API key — virksomhetssertifikat handling, JWT signing, token caching, and scope assertion stay server-side.

Use cases

  • File MVA, A-melding, or skattemelding on behalf of many client companies every period without a human logging in per action
  • Fetch restricted Tier 2 data about a company that is not your own
  • Perform delegated actions programmatically when they do not require a human step-up signing event
  • Confirm that a delegation is in place before attempting an action

Requirements

  • A Maskinporten OAuth2 client registered for the integrating organization, bound to a virksomhetssertifikat (Buypass or Commfides) plus a JWK upload
  • Digdir bruksvilkår signed in Samarbeidsportalen by someone with signature authority for the organization
  • An Altinn System Register registration for the integrating party
  • A per-target delegation: each target company adds the System User in its own Altinn portal and grants it specific rights

Authentication

Method: api_key · Scopes: read:altinn

The agent presents an Apier consumer API key (Authorization: Bearer). Apier holds the Maskinporten client and produces the Maskinporten + Altinn round-trip on the agent's behalf; no government credential is exposed to the caller.

Common errors

  • AUTH_NO_DELEGATION

    The target organization has not delegated system-user access to Apier, so the rule engine cannot read delegated data or act for it.

    Fix: Ask the target company to create a system user in Altinn and delegate access to Apier — this is a human step the agent cannot perform itself (handover actor: altinn_user).

  • SCOPE_MISSING

    The API key lacks the scope this endpoint requires.

    Fix: Mint or update a key with the required scope (e.g. read:altinn) via the account key endpoints.

Related topics

Related APIs

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

  • auth.delegate
  • auth.permissions
  • auth.acting_capacity
  • fullmakt.request
  • fullmakt.status
  • fullmakt.revoke

Related MCP tools

Registered tools on the Apier MCP server.

  • check_authorization
  • list_acting_capacity
  • request_fullmakt
  • check_fullmakt
  • revoke_fullmakt