Utvikler-API

Altinn API

Altinn 3-integrasjon — uten å bygge System User-, Maskinporten- og delegerings-stacken 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.

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, tilgangspakke-autorisasjon, 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.
• Mappingen Altinn 2 → Altinn 3. En gammel Altinn 2-rolle mappes sjelden én-til-én mot en Altinn 3-tilgangspakke — én rolle deles ofte på flere pakker, eller flere roller smelter sammen til én. Å få mappingen feil feiler lukket i gateway-et.

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

Apiers Auth Gateway eier Maskinporten-JWT-client-assertion-flyten, token-mellomlagringen og Altinn 3 System User-delegerings-håndtrykket. Integrasjonen din sender én Bearer- API-nøkkel; gateway-et løser opp riktig Maskinporten-token og virksomhetens delegerings-scopes 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 gateway-et; 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 avstemmer Brønnøysund (enhetsregister), Skatteetaten (MVA-register, MVA-meldinger) og NAV (Aa-registeret-aggregater) til én normalisert selskapskontekst.
• Innsending med en sikkerhetsport. POST /api/v1/actions/execute kjører en dry-run- valideringssti (fem forhåndssjekker, ingen innsending) i dag; den bindende live-stien er gated og ennå ikke tilgjengelig — utover en engangs-godkjenningstoken og en aktiv delegering venter den på Maskinporten-produksjonsvalidering og godkjenning av Altinn-scope — så automatisering omgår aldri en menneskelig port.

Kodeeksempel

Selskapskontekst-endepunktet returnerer virksomhetens Altinn 3- delegeringstilstand sammen med de avstemte registerdataene. Start mot null-auth-sandkassen, 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 dry-run-validering i dag; bindende live-innsending og dens HMAC-signerte kvittering er gated 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. Provisjonér 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 sandkasse-speilet 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 gateway-et.
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 dry-run-validering, siden bindende live-innsending er gated 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 fix-steg — 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 delegerings-gated Altinn-lese-kall (for eksempel innsendingshistorikk) har virksomheten ingen aktiv System User-delegering for kontoen din; responsen forklarer hvem som må delegere, hvor og hvorfor. (Live-innsendingsstien viser en manglende delegering som en feilet forhåndssjekk i stedet.)
• 403 APPROVAL_TOKEN_REQUIRED — en bindende live-innsending krever en engangs-godkjenningstoken (et menneske må autorisere handlingen); forespørselen avvises før hvert oppstrøms-kall 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 — maskin-til-maskin-auth-laget 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 curl-es uten registrering; dokumentasjonen går gjennom System User-delegeringsflyten og innsendingsstien — dry-run-validering i dag, med bindende live-innsending gated og ennå ikke tilgjengelig.