Hvorfor er norske offentlige API-er så komplekse å integrere?
Vanskeligheten er ikke HTTP-en. Det er virksomhetssertifikatet du må skaffe, Maskinporten-klienten du må registrere og signere assertions med, bruksvilkårene du må avtale med Digdir, oppføringen i systemregisteret som gjør programvaren din mulig å finne, og delegeringen hver kunde må gi deg. Hver etat løste sin egen versjon av disse problemene, til sin egen tid, så delene passer ikke sammen slik én leverandørs API ville gjort. Forespørselen du til slutt sender er helt vanlig. Alt som står foran den er det ikke.
Hva innebærer oppsettet fra ende til ende?
Begynn med sertifikatet. Maskinporten autentiserer en klient med en signert JWT-assertion, og nøkkelen bak den assertionen er forankret i et virksomhetssertifikat utstedt til en enhet registrert i Brønnøysund. Å skaffe et er et kjøp fra en sertifikatutsteder med en identitetskontroll knyttet til seg, og det utløper, så fornyelsen havner i noens kalender så lenge integrasjonen lever.
Så klienten og papirarbeidet. Du registrerer en Maskinporten-klient, laster opp den offentlige halvdelen av et nøkkelpar, og avtaler bruksvilkår med Digdir for de scopene du har tenkt å bruke. Deretter, for alt som skal skje på vegne av en kunde, legger du til en oppføring i Altinn systemregister slik at programvaren din finnes som en navngitt ting en kunde kan finne og gi rettigheter til. Ingen av stegene er vanskelige hver for seg. Problemet er at de kommer etter hverandre og at hvert av dem har sin egen godkjenningsrunde.
Først da kommer du til delegeringen, som er steget som aldri tar slutt: hver kunde gir systemet ditt sin egen tilgang, og hver kunde kan snevre den inn eller trekke den tilbake senere. Og først etter alt dette begynner koden du faktisk ble ansatt for å skrive. Har du noen gang lurt på hvorfor et to ukers integrasjonsestimat ble til et kvartal, er denne sekvensen som regel svaret.
| Steg | Hva det koster deg | Kan det megles? |
|---|---|---|
| Virksomhetssertifikat | Et kjøp med identitetskontroll, pluss en fornyelsessyklus som gjentar seg så lenge integrasjonen lever. | Ja. Sertifikatet og fornyelsen tilhører megleren. |
| Maskinporten-klient | Registrering, generering og opplasting av nøkkelpar, og nøkkelrotasjon etter en plan deretter. | Ja. Koden din håndterer aldri et offentlig token. |
| Bruksvilkår med Digdir | En godkjenningsrunde utenfor din kontroll, per scope du har tenkt å bruke. | Ja, for de scopene megleren allerede har. |
| Oppføring i Altinn systemregister | Å registrere programvaren din slik at kunder kan finne den ved navn og gi den rettigheter. | Ja. Kunder gir rettigheter til meglerens registrerte system. |
| Delegering per kunde | En flyt du tar hver kunde gjennom, og sjekker på nytt før hver handling. | Nei. Bare kunden kan gi myndighet over sine egne forhold. |
| Normalisering av skjema | Hvert register svarer i sin egen form; du forener dem og vedlikeholder koblingen. | Ja. Ett normalisert skjema på tvers av kilder. |
Hvor stopper de fleste integrasjonene opp?
Ved de to stegene som venter på noen andre. Utstedelse av sertifikat og godkjenning av bruksvilkår er ikke utviklingsoppgaver, så de reagerer ikke på de vanlige virkemidlene: du kan ikke parallellisere dem, du kan ikke estimere dem ut fra ditt eget teams hastighet, og du kan ikke bli ferdig med dem i en sprint ved å bestemme deg for det. Team som planlegger for dette starter anskaffelsessporet dag én og bygger mot noe annet i mellomtiden. Team som ikke gjør det, oppdager i uke seks at koden aldri var flaskehalsen.
Den andre stoppen er arkitektonisk og dukker opp senere. Det er øyeblikket et team innser at delegeringen ikke er et engangssteg ved innrullering, men en varig tilstand kundene endrer uten varsel. En integrasjon bygget på antakelsen om at en tilkoblet kunde forblir tilkoblet, kommer til å bestå alle testene og så feile i produksjon første gang noen i en økonomiavdeling rydder i tilgangslisten sin. Å designe tilbaketrekkingsstien tidlig er billigere enn å ettermontere den.
En tredje fanger dem som har portert fra den gamle plattformen. Altinn 2 ble avviklet 19. juni 2026, så enhver veiledning, ethvert eksempel og enhver intern wiki-side som beskriver Altinn 2-endepunkter, beskriver noe som ikke lenger svarer. Og det finnes ingen bredere dør: Altinn bekreftet i mai 2026 at serviceowner-instansscopes er forbeholdt offentlige etater, så den kundedelegerte modellen er den eneste som er tilgjengelig for en kommersiell integratør.
Hvordan tester jeg uten produksjonstilgang?
Bruk en nøkkelløs sandkasse og få dataformen riktig mens papirarbeidet går sin gang. Apiers offentlige sandkasse speiler produksjonens responsformer fra syntetiske norske testdata, krever verken nøkkel eller sertifikat, og er deterministisk: samme forespørsel gir samme kropp, så du kan asserte på den i en testsuite framfor å skrive tester som tåler variasjon.
Feilstier er også testbare, og det betyr mer enn lykkestien her. En simulate_error-parameter injiserer tilfellene for manglende delegering, ugyldig token, validering og manglende scope, slik at feilhåndteringen din møter hvert av dem før en reell kunde gjør det. Og sandkassen kaller aldri et offentlig system på noe verb, som er egenskapen som gjør det trygt å peke en testsuite, eller en autonom agent, mot den uten å tenke seg om to ganger.
Det sandkassen ikke kan si deg, er noe som helst om en reell innsending. Det er en grense det er verdt å si rett ut framfor å oppdage: den beviser at klienten din er riktig og beviser ingenting om rundturen til det offentlige. Start på sandkassen for en klipp-og-lim-forespørsel, og se veiledningen om raskeste vei for hvor langt du kommer før noen legitimasjon finnes.
Gjør det første kallet
Det første kallet utløser en feilsti med vilje, fordi det er den koden du faktisk kommer til å bruke tid på. Det andre er produksjonsoppslaget med legitimasjonskjeden på den andre siden.
# Nøkkelløs sandkasse: ingenting av oppsettskjeden gjelder her.
curl -s "https://www.apier.no/api/v1/sandbox/public/company/999999999/context?simulate_error=missing_delegation"// Produksjonsoppslag. Legitimasjonskjeden ligger på andre siden.
const res = await fetch(
"https://www.apier.no/api/v1/company/999999999/context",
{ headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` } },
);
if (!res.ok) {
// Strukturert feil, identisk i form på tvers av alle endepunkter.
const { error_code, explanation } = await res.json();
throw new Error(`${error_code}: ${explanation.summary}`);
}Ofte stilte spørsmål
- Hvorfor kan jeg ikke bare kalle Altinn med en API-nøkkel?
- Fordi Altinn ikke utsteder API-nøkler. Hvert kall bærer et Maskinporten-token som viser hvilken virksomhet du er, og det tokenet hentes med en JWT signert av en nøkkel forankret i et virksomhetssertifikat utstedt til en registrert norsk enhet. Alt som gjøres på vegne av en kunde krever i tillegg kundens delegering. HTTP-kallet er enkelt; legitimasjonskjeden bak er arbeidet.
- Hva er et virksomhetssertifikat, og trenger jeg et?
- Det er et sertifikat utstedt til en registrert virksomhet, og det er det som forankrer nøkkelen du signerer Maskinporten-assertions med. Du trenger et hvis du integrerer direkte. Gjennom en megler tilhører det megleren, noe som også betyr at fornyelsessyklusen og nøkkelrotasjonen tilhører dem framfor å dukke opp i din backlog annethvert år.
- Kan jeg bruke Altinns serviceowner-API-er i stedet?
- Nei, og det kan ingen annen privat integratør heller. Altinn bekreftet i mai 2026 at serviceowner-instansscopes er forbeholdt offentlige etater. Enhver kommersiell integrasjon går gjennom den kundedelegerte systembruker-modellen, så delegeringsflyten er ikke et valgfritt lag du kan utsette til en senere leveranse.
- Er Altinn 2 fortsatt et alternativ?
- Nei. Altinn 2 ble avviklet 19. juni 2026, så Altinn og Altinn 3 betyr nå det samme, og det finnes ingen gammel vei å falle tilbake på. Leser du en integrasjonsveiledning som beskriver Altinn 2-endepunkter, beskriver den noe som ikke lenger svarer.
- Hvor lang tid tar oppsettet?
- Ingen kan svare ærlig på det, fordi kalenderen settes av steg som avhenger av andre organisasjoner framfor av din utviklingskapasitet. Utstedelse av sertifikat og godkjenning av bruksvilkår er ikke oppgaver du blir fortere ferdig med ved å sette flere folk på dem. Den skjevheten er grunnen til å starte mot en sandkasse og behandle anskaffelsessporet som et parallelt løp.