Utvikler-API

Maskinporten API

Norsk maskin-til-maskin-autentisering uten å eie sertifikatet, JWT-signeringen og livssyklusen for nøkkelrotasjon.

Hva er Maskinporten?

Maskinporten er Norges OAuth2-baserte autorisasjonsserver for maskin-til-maskin-tilgang, driftet av DigDir. De fleste norske offentlige API-er (Altinn 3, Skatteetaten og andre) krever et Maskinporten-tilgangstoken før de svarer.

Trenger du hele autentiseringskjeden i rekkefølge? Hvordan autentiserer jeg meg mot norske offentlige API-er? går gjennom virksomhetssertifikatet, nøkkelparet, JWT-en du signerer og tokenvekslingen steg for steg.

Hvordan autentiserer jeg mot Maskinporten?

Å få et enkelt Maskinporten-token på den konvensjonelle måten er et oppsett i flere steg, og tokenene utløper:

• Sertifikat og klient. Kjøp et virksomhetssertifikat fra Buypass eller Commfides, onboard gjennom Samarbeidsportalen, og registrer en Maskinporten-klient med et RSA-nøkkelpar.
• JWK og den signerte assertionen. Last opp den offentlige nøkkelen som en JWK, bygg deretter og RS256-signer en JWT-client-assertion ved hver tokenforespørsel, med riktige issuer-, audience-, scope- og expiry-claims.
• Scopetildelinger og rotasjon. Be om hvert API-scope, hold test- og produksjonsmiljøene adskilt, forny tokens før de utløper, og roter signeringsnøkkelen etter tidsplan. En feil i klokkeavvik eller audience får vekslingen til å feile stille.

Hele flyten, og de ti fallgruvene som hver koster en dag, er skrevet ned i Maskinporten-guiden for utviklere.

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

Apier holder virksomhetssertifikatet og Maskinporten-klienten i Auth Gateway. Integrasjonen din autentiserer mot Apier med én Bearer-API-nøkkel; Apier presenterer den signerte JWT-client-assertionen for Maskinporten, mellomlagrer tokenet så lenge det varer, fornyer før utløp og roterer signeringsnøkkelen på egen tidsplan etter en publisert rutinebeskrivelse. Det rå OAuth-tokenet returneres aldri til koden din og logges aldri. Bare tidsstempel, scope og suksess/feil registreres.

• Ingen nøkkelpar, ingen JWK, ingen assertion. Du genererer aldri en nøkkel, laster aldri opp en JWK og signerer aldri en JWT. Sertifikatlivssyklusen er gatewayens problem.
• Scopes tilordnet i gatewayen. API-nøkkelen din bærer scopes på Apier-nivå (read:brreg, read:altinn, read:actions og så videre); de underliggende scopetildelingene i Maskinporten for hver oppstrøm løses opp for deg.
• Samme broker for hver oppstrøm. Tokenet bak en Altinn 3-handling (prøveinnsending i dag; bindende innsending i produksjon er låst og ennå ikke tilgjengelig) og tokenet som leser en Skatteetaten MVA-melding kommer begge fra den samme brokerte Maskinporten-klienten, så du integrerer én gang.

Kodeeksempel

Forskjellen er at det ikke ligger noe Maskinporten-token i forespørselen, fordi Apier hentet det for deg.

# One Bearer API key. No virksomhetssertifikat, no JWK, no signed
# JWT client-assertion, no Maskinporten token in your code — Apier
# brokers all of that at the gateway.
curl -H "Authorization: Bearer apier_live_<your_key>" \
  "https://www.apier.no/api/v1/company/991825827/obligations"

# No key at all — zero-auth sandbox against synthetic org 999999999.
curl https://www.apier.no/api/v1/sandbox/public/company/999999999/obligations

Hvor finner jeg API-referansen?

Den fullstendige API-referansen ligger i OpenAPI 3.1-spesifikasjonen og utviklerdokumentasjonen; rutinebeskrivelsen for nøkkelrotasjon som Apier følger, er publisert ved siden av.

• OpenAPI 3.1-spesifikasjon (/openapi.json)
• Utviklerdokumentasjon
• Rutinebeskrivelse for nøkkelrotasjon i Maskinporten

Hva bruker utviklere det brokerte tokenet til?

• Lese Skatteetaten Tier 2-data (MVA-register, MVA-meldinger, skatteoppgjør) uten å sette opp de tre scopene i Maskinporten selv. Flaten er bygget, men ennå ikke i drift: scopene hos Skatteetaten er til behandling eller avslått, så den venter på godkjenning.
• Kjør en Altinn 3 System User-innsending som prøveinnsending. Bindende innsending i produksjon er låst og ennå ikke tilgjengelig, men Maskinporten-leddet er allerede håndtert.
• Lever en integrasjon mot norsk forvaltning i et produkt som onboarder mange kunder, uten et prosjekt med sertifikat og rotasjon per kunde.

Hvordan kommer jeg i gang med Maskinporten?

Du rører aldri Maskinporten-tokenleddet. Å komme i gang handler om Apier-nøkkelen din og, for å handle på vegne av en virksomhet, den virksomhetens Altinn-delegering. Bindende handlinger i produksjon på vegne av en virksomhet er låst og ennå ikke tilgjengelige i dag; dagens flyt validerer som prøveinnsending uten å sende inn til et statlig system i drift.

1. Opprett en Apier-API-nøkkel og gi den scopene oppstrømmene dine trenger (for eksempel read:altinn eller read:actions).
2. Prøv det mot sandkassen uten autentisering først. Kjør curl mot sandkassespeilet for syntetisk org 999999999, uten nøkkel og uten sertifikat, for å bekrefte klientoppkoblingen din.
3. Pek den samme klienten mot produksjonsverten med Bearer-nøkkelen din. Det brokerte Maskinporten-tokenet hentes på serveren, så det er ingenting å konfigurere på tokenleddet.
4. For å handle på vegne av en virksomhet, få den til å gi Apier-kontoen din en Altinn 3 System User-delegering, og verifiser deretter med en handleevnesjekk før hvert bindende kall.

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, og ingen rå Maskinporten- eller oppstrømsinterne detaljer lekker ut. Hver respons bærer en X-Correlation-ID du kan oppgi til support.

• 401 AUTH_MISSING: Headeren Authorization: Bearer mangler eller er feilformatert; en forvansket header strippes på kanten, så bekreft at nøkkelen sendes intakt.
• 401 AUTH_INVALID_KEY: API-nøkkelen gjenkjennes ikke eller er tilbakekalt.
• 403 SCOPE_INSUFFICIENT: Nøkkelen bærer ikke scopet endepunktet krever.
• 403 AUTH_NO_DELEGATION: På et lesekall som krever delegering (Tier 2-selskapsdata, innsendingshistorikk), har virksomheten ikke gitt kontoen din en Altinn System User-delegering; responsen forklarer hvem som må delegere, hvor og hvorfor.
• 502 MASKINPORTEN_TOKEN_FAILED: Apier klarte ikke å hente det brokerte tilgangstokenet fra Maskinporten for kallet (tokenleddet feilet); som regel forbigående, så prøv igjen etter en kort pause.

Vanlige spørsmål

Relaterte utviklersider

• Altinn-API: Altinn 3-flaten det brokerte tokenet autoriserer mot.
• Altinn for AI-agenter: MCP-serveren over den samme brokerte autentiseringen.
• Skatteetaten-API: flaten for MVA-meldingen som det brokerte tokenet autoriserer mot.
• Webhooks-API: Abonner på endringsarkivhendelser over den samme brokerte autentiseringen.
• Maskinporten-guiden for utviklere: den dype veiledningen hvis du vil kjøre flyten selv.
• Dokumentasjon og Apier-forsiden.

Kom i gang

Sandkassen trenger ingen legitimasjon i det hele tatt; dokumentasjonen dekker scopene API-nøkkelen din bærer og hvordan Apier tilordner dem til scopes i Maskinporten.