Utvikler-API

Altinn API

Altinn 3-integrasjon uten å bygge System User, Maskinporten og delegering på nytt selv.

Hva er Altinn-API-et?

Altinn er Norges felles plattform for digital dialog mellom næringsliv og offentlig sektor: innsendinger, skjemaer, korrespondanse og maskin-til-maskin-API-er på tvers av Skatteetaten, Brønnøysund, Nav og dusinvis av andre etater.

Vil du ha den tekniske gjennomgangen? Hvordan integrerer jeg med Altinn 3? går gjennom Maskinporten-tokenet, systembrukerdelegeringen og det første kallet steg for steg.

Hvordan autentiserer jeg mot Altinn 3?

DigDir la ned Altinn 2 19. juni 2026. De eldre Altinn 2-tjenestene (SOAP-endepunkter, rollebasert autorisasjon) sluttet å svare den dagen, og Altinn 3 (REST, Instances-API-et, tilgangspakkeautorisasjon, og System Users for maskintilgang) ble det eneste Altinn-API-et. Å bygge direkte mot det betyr å eie flere bevegelige deler samtidig:

• En maskinidentitet. Et virksomhetssertifikat fra Buypass eller Commfides, en Maskinporten-klient med et RSA-nøkkelpar, og en oppføring i Altinn System Register, før en eneste forespørsel autentiserer.
• Autoritet per virksomhet. Hver virksomhet du handler for må gi en System User-delegering avgrenset til de riktige tilgangspakkene. Delegeringer utløper, tilbakekalles, og må gis på nytt på virksomhetens side.
• Tilordningen Altinn 2 → Altinn 3. En gammel Altinn 2-rolle tilordnes sjelden én-til-én til en Altinn 3-tilgangspakke. Én rolle deles ofte på flere pakker, eller flere roller smelter sammen til én. Blir tilordningen feil, stopper gatewayen forespørselen.

Hvordan håndteres tilgang på vegne av en virksomhet?

Apiers Auth Gateway eier Maskinporten-JWT-client-assertion-flyten, tokenmellomlagringen og Altinn 3 System User-delegeringshåndtrykket. Integrasjonen din sender én Bearer- API-nøkkel; Apier løser opp riktig Maskinporten-token og virksomhetens scopes for delegering ved forespørselstidspunkt, og returnerer aldri det rå OAuth-tokenet til koden din.

• Én legitimasjon, N virksomheter. Ett virksomhetssertifikat og én Maskinporten-klient bor i gatewayen; autoritet per virksomhet kommer fra hver virksomhets Altinn 3 System User-delegering. Utløpte eller tilbakekalte delegeringer feiler lukket.
• Avstemt tilstand på tvers av etater. Den samme flaten som eksponerer Altinn-delegeringstilstand normaliserer Brønnøysund (enhetsregister, inkludert MVA-registreringsstatus) til én selskapskontekst i dag. Skatteetaten-delene (MVA-meldinger) og Nav (aggregater fra Aa-registeret) er bygget, men ikke i drift: MVA-meldingsvalidering har godkjent scope, lesetilgangen til MVA-meldinger avventer behandling, og Navs Aa-registeret er ennå ikke søkt om.
• Innsending med en sikkerhetsport. POST /api/v1/actions/execute kjører en prøveinnsending (fem forhåndssjekker, ingen faktisk innsending) i dag; den bindende stien i produksjon er låst og ennå ikke tilgjengelig. Utover et godkjenningstoken til engangsbruk og en aktiv delegering venter den på Maskinporten-produksjonsvalidering og godkjenning av Altinn-scope, så automatisering omgår aldri en menneskelig port.

Kodeeksempel

Selskapskontekstendepunktet returnerer virksomhetens Altinn 3- delegeringstilstand sammen med de avstemte registerdataene. Start mot sandkassen uten autentisering, pek deretter den samme klienten mot produksjonsverten med nøkkelen din.

# Zero-auth sandbox — synthetic fixture org 999999999.
# data.* mirrors the production shape, including Altinn delegation state.
curl https://www.apier.no/api/v1/sandbox/public/company/999999999/context

# Production — one Bearer API key; the per-org authority comes from
# the org's active Altinn 3 System User delegation, resolved by Apier.
curl -H "Authorization: Bearer apier_live_<your_key>" \
  "https://www.apier.no/api/v1/company/991825827/context"

Hvor finner jeg API-referansen?

Den fullstendige API-referansen ligger i OpenAPI 3.1-spesifikasjonen og utviklerdokumentasjonen; System User-delegeringsflyten er skrevet ned steg for steg i sin egen guide.

• OpenAPI 3.1-spesifikasjon (/openapi.json)
• Utviklerdokumentasjon
• Altinn System Users-guide

Hva bygger utviklere på det?

• Les en virksomhets aktive Altinn 3-delegeringer og tilgangspakker for å avgjøre hva produktet ditt har lov til å gjøre på dens vegne.
• Kjør en MVA-melding gjennom Altinn 3-innsenderen som prøveinnsending i dag; bindende innsending i produksjon og dens HMAC-signerte kvittering er låst og ennå ikke tilgjengelig.
• Løs opp hvem som lovlig kan handle for en virksomhet (signaturrett, prokura og de delegerte System User-scopene) før du forsøker en bindende handling.

Hvordan kommer jeg i gang?

Å koble opp en Altinn 3-integrasjon gjennom Apier er fire steg. Klienten din rører aldri Maskinporten- eller System Register-oppsettet.

1. Opprett en Apier-API-nøkkel og gi den scopene du trenger: read:altinn for delegeringstilstand, og read:actions hvis du skal sende inn.
2. Koble klienten din mot sandkassespeilet uten autentisering (curl mot syntetisk org 999999999, uten nøkkel og uten sertifikat) og bekreft responsformen.
3. Pek den samme klienten mot produksjonsverten med Bearer- nøkkelen din; Maskinporten-tokenet og System User-håndtrykket løses opp i gatewayen.
4. Få hver virksomhet til å gi Apier-kontoen din en Altinn 3 System User-delegering, og kjør deretter en handleevnesjekk før hver innsending, i dag som prøveinnsending, siden bindende innsending i produksjon er låst og ennå ikke tilgjengelig.

Hvordan håndterer jeg feil?

Hver feil følger Apiers strukturerte Compliance Explainer-format: en error_code, en lesbar explanation (med valgfri explanation.details) og konkrete rettesteg, uten at rå Altinn- eller Maskinporten-interne detaljer lekker. Hver respons bærer en X-Correlation-ID du kan oppgi til support.

• 403 AUTH_NO_DELEGATION: På et Altinn-lesekall som krever delegering (for eksempel innsendingshistorikk), har virksomheten ingen aktiv System User-delegering for kontoen din; responsen forklarer hvem som må delegere, hvor og hvorfor. (Innsendingsstien i produksjon viser en manglende delegering som en feilet forhåndssjekk i stedet.)
• 403 APPROVAL_TOKEN_REQUIRED: En bindende innsending i produksjon krever et godkjenningstoken til engangsbruk (et menneske må autorisere handlingen); forespørselen avvises før hvert oppstrømskall inntil tokenet leveres i X-Approval-Token-headeren.
• 400 VALIDATION_FAILED: Payloaden feilet skjemavalidering; rett feltene listet i explanation.details og send på nytt.
• 422 IDEMPOTENCY_KEY_MISMATCH: Den samme Idempotency-Key ble gjenbrukt med en annen body; bruk en fersk nøkkel for en endret forespørsel. (En duplikat som fortsatt er underveis returnerer 409 IDEMPOTENCY_IN_PROGRESS i stedet.)
• 502 GOVERNMENT_VALIDATION_REJECTED: Altinn eller mottakeretaten avviste innholdet (format eller totaler); forhåndsvalider med ?dry_run=true først.

Vanlige spørsmål

Relaterte utviklersider

• Maskinporten-API: autentiseringslaget under Altinn 3.
• Brønnøysund (BRREG) API: selskapsoppslag og registerdataene Altinn-autoritet løses opp mot.
• Altinn for AI-agenter: MCP-serveren og deterministisk utførelse på tvers av etater.
• Altinn System User API: System User-delegeringsflaten denne siden autentiserer mot.
• Webhooks API: Abonner på Altinn-baserte endringshendelser i stedet for polling.
• Dokumentasjon og Apier-forsiden.

Kom i gang

Sandkassen kan kjøres med curl uten registrering; dokumentasjonen går gjennom System User-delegeringsflyten og innsendingsstien: prøveinnsending i dag, med bindende innsending i produksjon låst og ennå ikke tilgjengelig.