Utvikler-API

Maskinporten API

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

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.

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 assertion-en. Last opp den offentlige nøkkelen som en JWK, bygg deretter og RS256-signer en JWT-client-assertion ved hver token-forespørsel, med riktige issuer-, audience-, scope- og expiry-claims.
• Scope-grants 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; gateway-et presenterer den signerte JWT-client-assertion-en for Maskinporten, mellomlagrer tokenet så lenge det varer, fornyer før utløp og roterer signeringsnøkkelen på egen tidsplan etter en publisert runbook. 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. Sertifikat-livssyklusen er gateway-ets problem.
• Scopes mappet i gateway-et. API-nøkkelen din bærer Apier-nivå-scopes (read:brreg, read:altinn, read:actions og så videre); de underliggende Maskinporten-scope-grantene for hver oppstrøm løses opp for deg.
• Samme broker for hver oppstrøm. Tokenet bak en Altinn 3-handling (dry-run-validering i dag; bindende live-innsending er gated og ennå ikke tilgjengelig) og tokenet som leser en Skatteetaten MVA-melding kommer begge fra den samme brokerte Maskinporten-klienten — du integrerer én gang.

Kodeeksempel

Forskjellen er hva som mangler: det er ingen Maskinporten-token i forespørselen, fordi Apier hentet den 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; nøkkelrotasjons-runbooken gateway-et følger er publisert ved siden av.

• OpenAPI 3.1-spesifikasjon (/openapi.json)
• Utviklerdokumentasjon
• Maskinporten nøkkelrotasjons-runbook

Hva bruker utviklere det brokerte token-et til?

• Les Skatteetaten Tier 2-data (MVA-register, MVA-meldinger, skatteoppgjør) uten å sette opp de tre Maskinporten-scope-grantene selv.
• Kjør en Altinn 3 System User-innsending som dry-run-validering — bindende live-innsending er gated 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 sertifikat-og-rotasjons-prosjekt per kunde.

Hvordan kommer jeg i gang med Maskinporten?

Du rører aldri Maskinporten-token-leddet — å komme i gang handler om Apier-nøkkelen din og, for å handle på vegne av en virksomhet, den virksomhetens Altinn-delegering. Bindende live-handlinger på vegne av en virksomhet er gated og ennå ikke tilgjengelig i dag — dagens flyt validerer som dry-run uten å sende inn til et live statlig system.

1. Provisjonér 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 null-auth-sandkassen først — curl sandkasse-speilet mot syntetisk org 999999999, uten nøkkel og uten sertifikat, for å bekrefte klient-oppkoblingen din.
3. Pek den samme klienten mot produksjonsverten med Bearer-nøkkelen din. Det brokerte Maskinporten-tokenet hentes server-side — det er ingenting å konfigurere på token-leddet.
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 fix-steg — og ingen rå Maskinporten- eller oppstrøms-interne detaljer lekker ut. Hver respons bærer en X-Correlation-ID du kan oppgi til support.

• 401 AUTH_MISSING — Authorization: Bearer-headeren 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 delegerings-gated lese-kall (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 — gateway-et klarte ikke å hente det brokerte Maskinporten-tilgangstokenet for kallet (token-leddet 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 auth-en.
• Skatteetaten-API — MVA-melding-flaten det brokerte tokenet autoriserer mot.
• Webhooks-API — abonner på endringsarkiv-hendelser over den samme brokerte auth-en.
• Maskinporten-guiden for utviklere — den dype how-to-en 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 gateway-et mapper dem mot Maskinporten.