Altinn 3, Maskinporten og systembruker — slik fungerer maskinell innsending

Hva integrasjonen gjør

Ikke teknisk? Hopp rett til «I klartekst — forklart uten sjargong» lenger ned, så slipper du fagspråket og får hele bildet med hverdagsord.

Macct sender inn til det offentlige på vegne av kunden, uten at kunden deler passord eller logger inn manuelt. Følgende går maskinelt:

• Skattekort til arbeidsgiver — henter fra Skatteetaten hvor mye skatt som skal trekkes av de ansattes lønn.
• MVA-melding — momsoppgaven; leveres via en Altinn 3-app hos Skatteetaten.
• Næringsspesifikasjon + skattemelding (AS) — tallgrunnlaget (tidligere kalt RF-1167) og selve skattemeldingen for aksjeselskapet.
• Årsregnskap — sendes som skjema RR0002 til Regnskapsregisteret i Brønnøysund via Altinn.
• A-melding — den månedlige lønns- og skatterapporten; leveres som JSON direkte til Skatteetatens innrapporterings-API (den gamle Altinn 2-kanalen stengte 15. juni 2026).
• Aksjonærregisteroppgave — oversikten over hvem som eier aksjene i selskapet. RF-1086 bygges i Skatteetatens offisielle skjemaformat og sendes til det nye aksjonærregister-API-et i en 3-stegs flyt (hovedskjema → ett underskjema per aksjonær → bekreft).

Tre byggeklosser gjør dette mulig: Maskinporten (et slags ID-kort som lar én datamaskin bevise hvem den er overfor en annen — driftet av staten ved Digdir), en systembruker (fullmakten du gir Macct, godkjent med BankID i Altinn), og Altinn / Skatteetaten (der innsendingen faktisk leveres). Organisasjonsregisteret hos Brønnøysundregistrene brukes til å sjekke organisasjonsnummeret, rollen din og at selskapet er i orden når du registrerer deg. Alle tre er forklart nærmere rett under.

I klartekst — forklart uten sjargong

Det meste av siden er teknisk. Her er det samme forklart på vanlig norsk, med et bilde du kjenner igjen fra hverdagen.

Tenk på det offentlige — Skatteetaten, Brønnøysund — som en samling låste kontorer der du leverer papirer. Til vanlig går du dit selv, logger inn med BankID og leverer. Macct gjør den jobben for deg. Men for at en datamaskin skal få slippe inn og levere på dine vegne, må tre ting være på plass:

Kort oppsummert: Maskinporten = hvem maskinen er. Systembruker = hva den får lov til, og for hvem. Altinn = hvor den leverer. Resten av siden er detaljene bak hver av disse tre.

Hva merker du som kunde? Nesten ingenting. Du godkjenner én lenke med BankID den aller første gangen. Etterpå fører Macct regnskapet og forbereder innsendingene, og du trykker «send» når du selv er klar. Ingenting går automatisk — verken til Skatteetaten eller Brønnøysund — uten at du har godkjent det.

Liten ordliste

Resten av siden bruker disse ordene om og om igjen. Har du dem, leser du alt annet uten å stoppe opp.

Digdir / Maskinporten: klient, JWT-grant og scopes

Kort fortalt: Macct ber staten om et midlertidig adgangskort ved å vise et signert digitalt «stempel». Kortet gjelder bare de oppgavene Macct har fått godkjent på forhånd — kalt scopes — for eksempel å hente skattekort eller levere MVA.

Tre ting å vite om Maskinporten:

• Én klient per miljø. Test og produksjon er helt adskilte verdener med hver sin klient, hver sin nøkkel og hver sin scope-tildeling.
• Autentisering med signert nøkkel. Klienten beviser hvem den er med en nøkkel registrert i Digdirs Samarbeidsportal — ingen passord noe sted.
• Token per behov. Klienten signerer en kort JWT («her er jeg, og jeg vil ha disse scopene») og bytter den mot et access token som varer i noen minutter.

POST https://maskinporten.no/token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=<signert JWT: iss=clientId, aud=maskinporten, scope=...>

Scopene vi bruker

Systembruker: System Register, request og BankID-godkjenning

Kort fortalt: Dette er selve fullmakten din, og den settes opp i tre steg: Macct registrerer seg som «system» hos Altinn (gjøres bare én gang), lager så en forespørsel for ditt selskap, og til slutt godkjenner du den med BankID. Først da kan Macct levere på vegne av deg.

En systembruker er kundens fullmakt til fagsystemet i Altinn. Flyten er tre steg:

1. Registrer systemet (én gang per miljø)

Fagsystemet registreres i Altinns System Register med en systID på formen <leverandør-orgnr>_macct, klient-ID-en(e) fra Maskinporten, og hvilke rettigheter og tilgangspakker systemet forvalter.

POST {altinn}/authentication/api/v1/systemregister/vendor
{ "id": "<orgnr>_macct", "vendor": { "ID": "0192:<orgnr>" },
  "clientId": ["..."], "rights": [...], "accessPackages": [...],
  "allowedRedirectUrls": ["https://macct.no/altinn/callback"] }

2. Opprett en systembruker-forespørsel per kunde

POST {altinn}/authentication/api/v1/systemuser/request/vendor
{ "systemId": "<orgnr>_macct",
  "partyOrgNo": "<kundens orgnr>",
  "externalRef": "selskap-123",
  "rights": [ { "resource": [ { "id": "urn:altinn:resource", "value": "app_skd_formueinntekt-skattemelding-v2" } ] }, ... ],
  "accessPackages": [ { "urn": "urn:altinn:accesspackage:merverdiavgift" }, ... ],
  "redirectUrl": "https://macct.no/altinn/callback" }
→ svar inneholder en confirmUrl (am.ui.altinn.no/.../systemuser/request?id=...)

3. Kunden godkjenner med BankID

Kunden åpner confirmUrl og godkjenner i Altinn. Etter godkjenning slås den faktiske systembrukeren opp («bysystem»-listen), og en systemUserId lagres på kunden. Den brukes ikke direkte i tokenet — selve fullmakten bæres av externalRef + kundens orgnr (under).

Tilgangspakker vs. rettigheter (rights)

Kort fortalt: Altinn krever to slags tilgang samtidig — en bred «rolle-pakke» (at Macct får jobbe med regnskap og MVA i det hele tatt) og en konkret «nøkkel» til hver enkelt tjeneste. Mangler én av de to, blir leveringen avvist. Macct setter opp begge for deg.

Altinn 3 skiller mellom to fullmaktstyper, og innsending krever ofte begge:

• Rettigheter (rights) — peker på en konkret ressurs/app, f.eks. app_skd_formueinntekt-skattemelding-v2 (skattemelding), app_brg_aarsregnskap-vanlig-202406 (årsregnskap), ske-innrapportering-amelding (a-melding).
• Tilgangspakker (access packages) — rollebaserte «bunter» som Altinns policy-motor (PDP) krever for å instansiere enkelte apper. Vi bruker urn:altinn:accesspackage:regnskap-okonomi-rapport og urn:altinn:accesspackage:merverdiavgift.

Tokens: Maskinporten-token og Altinn-token-utveksling

Kort fortalt: Adgangskortet fra Maskinporten byttes inn i et «hus-spesifikt» kort hos Altinn, og knyttes til fullmakten din slik at leveringen havner på riktig selskap. Test-selskap og ekte selskap bruker hvert sitt system — de må aldri blandes, ellers finner ikke Altinn fullmakten.

For å handle på vegne av en annen virksomhet enn klient-eieren binder vi tokenet til systembrukeren via authorization_details (RAR-typen urn:altinn:systemuser):

authorization_details = [{
  "type": "urn:altinn:systemuser",
  "systemuser_org": { "authority": "iso6523-actorid-upis", "ID": "0192:<kundens orgnr>" },
  "externalRef": "selskap-123"
}]

Maskinporten-tokenet byttes deretter mot et Altinn-token for å nå Storage/App-API-ene:

GET {altinn}/authentication/api/v1/exchange/maskinporten
Authorization: Bearer <maskinporten-token med altinn:instances.write>
→ Altinn-JWT brukt mot app-instanser

Hvilket token mot hvilket API?

Den vanligste feilkilden i praksis er å bruke feil type token mot feil API. Regelen er enkel når man først ser den:

Per tjeneste: API-kall og parametere

Skattekort til arbeidsgiver

Direkte mot Skatteetatens «Skattekort for arbeidsgivere» (v3, forskudd-API) med et systembruker-bundet Maskinporten-token og scope skatteetaten:skattekorttilarbeidsgiver. Vert: api.skatteetaten.no (prod) / api-test.sits.no (test). Parametere: inntektsår, arbeidsgivers orgnr og den ansattes fødselsnummer. Svar: trekktype (tabell/prosent), tabellnummer og trekkprosent — som skrives på den ansatte og brukes i lønnskjøringen.

MVA-melding

Leveres via Altinn 3-appen mva-melding-innsending-v1 (instances.write + systembruker), ikke det avviklede direkte-API-et. To XML-dokumenter bygges: selve meldingen (mvamelding, namespace skattemeldingformerverdiavgift) og en innsendings-wrapper (mvameldinginnsending). Flyt:

1) POST .../instances              (opprett instans, instanceOwner = kundens orgnr)
2) PUT/POST data: mvamelding + wrapper  (erstatt auto-opprettet element)
3) PUT .../process/next            (data → confirmation → feedback)
→ kvittering: instanceOwnerPartyId/instanceGuid

Meldingen inneholder bl.a. skattleggingsperiode (to-måneders termin + år), fastsattMerverdiavgift, mvaSpesifikasjonslinje[], meldingskategori=alminnelig og skattepliktig>organisasjonsnummer. Valgfri forhåndsvalidering finnes på /api/mva/grensesnittstoette/mva-melding/valider.

A-melding

Leveres som JSON direkte til Skatteetatens innrapporterings-API — den gamle Altinn 2-kanalen (A02) stengte 15. juni 2026. Macct bygger det offisielle Leveranse-objektet fra lønnskjøringen: inntekter per mottaker, forskuddstrekk og utleggstrekk (negative per mottaker, positive summer i betalingsinformasjon) og arbeidsgiveravgift per sone — med OTP-premien som egen grunnlagslinje (tilskuddOgPremieTilPensjon), slik kodeverket krever. Tokenet er systembruker-bundet med scope skatteetaten:innrapporteringamelding.

POST /v1/innsending/{periode}/{opplysningspliktig}   (Leveranse-JSON + idempotencyKey-header)
GET  /v1/forsendelser/{forsendelseId}                (tilbakemelding når den er klar)

Tilbakemeldingen brukes til avstemming: Skatteetatens beregnede forskuddstrekk og arbeidsgiveravgift, KID/kontonummer og forfallsdato, pluss eventuelle avvik med alvorlighetsgrad. Som alt annet sendes a-meldingen aldri automatisk — den valideres først, og et menneske trykker «send».

Aksjonærregisteroppgave (RF-1086)

Leveres til Skatteetatens aksjonærregister-API i en 3-stegs flyt, i det offisielle skjemaformatet (hovedskjema 890/RF-1086 + ett underskjema 923/RF-1086-U per aksjonær, validert mot Skatteetatens XSD-er). Tokenet er systembruker-bundet med scope skatteetaten:innrapporteringaksjonaerregisteroppgave; hvert kall har påkrevd idempotencyKey.

1) POST /{aar}/1086H                          → hovedskjemaid
2) POST /{aar}/{hovedskjemaid}/1086U          (ett kall per aksjonær)
3) POST /{aar}/{hovedskjemaid}/bekreft?antall_underskjema=N → forsendelseId

Oppgaven følger samme godkjenningsløp som skattemeldingen (utkast → gjennomgang → godkjenn → send, med SHA-256-integritetskontroll) og sendes aldri automatisk. VPS-registrerte selskap blokkeres (VPS rapporterer for dem); selskap med flere aksjeklasser eller hendelser som fusjon/fisjon/ spleis henvises inntil videre til skatteetaten.no.

Årsregnskap (RR0002)

Leveres til Regnskapsregisteret via Altinn-appen app_brg_aarsregnskap-vanlig-202406:

• To dokumenter lastes opp: Hovedskjema (RR0002H_M — metadata) og Underskjema (RR0002U_M — resultat/balanse med detaljlinjer).
• Signeringen krever en person. Systemet fører prosessen frem til signeringssteget, men selve signeringen kan ikke utføres av en systembruker — Regnskapsregisteret krever av juridiske hensyn at en person signerer med ID-porten i Altinn (systembruker-signering avvises med 403). Fagsystemet klargjør og låser alt, personen signerer, og systemet fanger opp fullført prosess ved å polle instansen etterpå.
• Om app-navnet: suffikset -202406 er en versjonsdato Brønnøysund kan rullere ved nye årganger — navnet er derfor konfigurerbart hos oss, ikke fastspikret.

Næringsspesifikasjon og skattemelding (AS)

Skattemeldingen for AS er den mest sammensatte flyten. Den har tre deler:

• Bygg og godkjenn. Næringsspesifikasjonen (RF-1167-grunnlaget) bygges og godkjennes først; deretter genereres selve skattemeldingen (v2-format, pakket i skattemeldingOgNaeringsspesifikasjonRequest med base64-kodede deldokumenter). Innsending er aldri automatisk — status-løpet er DRAFT → READY_FOR_REVIEW → APPROVED → SUBMITTED, med SHA-256-integritetskontroll mellom stegene (en Macct-kontroll, ikke et offentlig krav) og en obligatorisk preflight-sjekk før noe sendes.
• Lever via Altinn-appen. Dokumentene lastes opp på en instans i app_skd_formueinntekt-skattemelding-v2 og prosessen drives frem til bekreftelses-steget.
• Personen bekrefter. Bekreftelses-steget (Task_2) må utføres av en person med ID-porten — se personkravet under. SUBMITTED settes først når Skatteetatens tilbakemelding faktisk sier validertOK, aldri bare fordi prosess-steget er passert.

Konvolutten må referere Skatteetatens eget utkast

Dette er lett å gå glipp av, og feilen viser seg først etter at personen har bekreftet: Skatteetaten har allerede et utkast til skattemelding for selskapet liggende, og innsendings-konvolutten må inneholde en referanse til akkurat det dokumentet (dokumentreferanseTilGjeldendeDokument) pluss Skatteetatens eget partsnummer for selskapet. Begge hentes fra hentSkattemelding-API-et rett før innsending:

GET https://api.skatteetaten.no/api/skattemelding/v2/{inntektsår}/{orgnr}
Authorization: Bearer <systembruker-bundet Maskinporten-token,
                       scope skatteetaten:formueinntekt/skattemelding>
Accept: application/xml

→ svar: dokumentid (f.eks. SKI:755:14847), dokumenttype
  (skattemeldingUpersonligUtkast) og partsnummer (10 sifre — IKKE orgnr)
→ begge legges inn i konvolutten før opplasting

Tre detaljer som må være riktige samtidig:

• Uten referansen avvises innsendingen med konvoluttIkkeRiktigFormatert i tilbakemeldingen. Kravet står i Skatteetatens API-dokumentasjon, men håndheves ikke av XSD-ene — XML-en kan altså validere grønt lokalt og likevel bli avvist. Det samme gjelder hvis organisasjonsnummeret brukes der partsnummeret skulle stått.
• Systembruker-bindingen er selve representasjonen. Et token med riktig scope, men uten systembruker i authorization_details, avvises med «Pålogget bruker har ikke nødvendige rettigheter i Altinn til å representere skattepliktig».
• Hent referansen ferskt per innsending. Utkastet hos Skatteetaten kan erstattes; en gammel dokumentid peker da på feil versjon.

Personkravet i siste ledd

Som for årsregnskapet krever Skatteetaten spor til en person bak innsendingen: fullføres bekreftelses-steget maskinelt med systembruker, leverer prosessen tilsynelatende — men tilbakemeldingen blir validertMedFeil / innkommendeForespoerselManglerSporTilUtfoerende. Riktig design er derfor at fagsystemet klargjør og låser innsendingen og stopper ved bekreftelsen, og at personen fullfører med ID-porten — i Altinn-portalen eller direkte i fagsystemet (sluttbruker-flyten under).

Personlig bekreftelse fra eget system (ID-porten sluttbruker-flyt)

Personen trenger ikke sendes til Altinn-portalen for bekreftelses-steget: et sluttbrukersystem kan la personen logge inn med ID-porten i systemets egen flyt og utføre bekreftelsen via API — samme mønster som Altinn dokumenterer for sluttbrukersystemer, og slik de store fagsystemene leverer. Registrer en «API-klient» i Digdirs Samarbeidsportal (grant authorization_code + PKCE S256; klientautentisering client_secret_post eller private_key_jwt), be om scope openid altinn:instances.write, og veksle personens access-token til et personlig Altinn-token:

GET {altinn}/authentication/api/v1/exchange/id-porten             (prod)
GET {altinn}/authentication/api/v1/exchange/id-porten?test=true   (TT02)
Authorization: Bearer <idporten-access-token>

→ PUT {app}/instances/{instans}/process/next    body: {"action":"confirm"}
  Authorization: Bearer <personlig-altinn-token>

Detaljer som er greie å vite om på forhånd:

• Samtykkesiden: ID-porten viser en «Godta / Avvis»-side for datadelings-scopene. Velger brukeren «Avvis», utstedes tokenet med kun openid/profile — og vekslingen svarer 403 uten body, fordi den krever minst ett altinn:-scope i tokenet. Samtykket huskes etter første «Godta».
• Lese-scopet er ikke selvbetjent i prod: altinn:instances.read lar seg ikke legge til selv i Samarbeidsportalens produksjonsmiljø. Be kun om altinn:instances.write — bekreftelsen er en skriveoperasjon, og vekslingen trenger bare ett altinn:-scope.
• ?test=true: TT02-vekslingen krever parameteren for tokens fra test.idporten.no (403 uten); i produksjon skal den ikke med.
• private_key_jwt: velges nøkkel i stedet for client secret, skal aud i client_assertion være ID-portens issuer (ikke token-endepunktet), og kid-en fra Samarbeidsportalen er påkrevd i JWT-headeren.
• Rask sanity-test: et token-kall med en dummy-kode skiller klientoppsettet fra resten av flyten — invalid_client betyr feil klientautentisering, invalid_grant betyr at klienten er riktig satt opp (koden var jo ugyldig med vilje).

Bekreftelsen bærer da spor til personen (kravet over), brukeren er aldri innom Skatteetatens visningsklient (se SMEVB-005 under fallgruvene), og statusregelen er uendret: «innsendt» settes først ved validertOK i tilbakemeldingen.

Fallgruver verdt å unngå

Punktene under er de som typisk koster mest tid. Macct er bygd for å håndtere disse situasjonene automatisk der det er mulig, slik at de i praksis sjelden er noe du trenger å tenke på.

Hva en Macct-kunde må gjøre

For at Macct skal kunne sende inn MVA-melding, årsregnskap, skattemelding m.m. på vegne av selskapet ditt, trenger vi én engangsgodkjenning fra deg:

1. Du får en lenke til Altinn (am.ui.altinn.no) fra Macct.
2. Du logger inn med BankID og godkjenner systembruker-forespørselen — du må ha en rolle på selskapet (typisk daglig leder eller styreleder, eller en delegert rolle) i Brønnøysund/Altinn.
3. Godkjenningen gir Macct en systembruker med nøyaktig de tilgangspakkene og rettighetene som står i forespørselen — verken mer eller mindre.

Du deler aldri passord, BankID-koder eller API-nøkler. Fullmakten er avgrenset, sporbar, og du kan når som helst trekke den tilbake i Altinn under Tilgangsstyring → Systemtilgang. Og selv med fullmakt på plass sender Macct aldri noe inn uten at det er utløst og godkjent — innsending krever alltid et eksplisitt menneskelig «send».