Trenger jeg Maskinporten-token eller Altinn-token, og hvordan veksler jeg?

Når holder det med et Maskinporten-token alene?

Start med hva tokenet er. Maskinporten autentiserer virksomheten din og utsteder et kortlevd JWT som bærer scopene klienten din har fått tildelt. Det tokenet beviser hvem du er overfor ethvert API der dokumentasjonen oppgir at Maskinporten-token godtas direkte. Dialogporten dokumenterer nettopp det: et sluttbrukersystem kan kalle det med et Maskinporten-token direkte, også varianten som identifiserer en systembruker som opptrer for en kunde, og tjenesteeier-systemer bruker Maskinporten-token der vekslingen er en mulighet framfor en plikt.

Den klassiske plattformen er den andre halvdelen av skillet. Altinn-apper og plattform-API-ene bak dem forventer et Altinn-token: dokumentasjonen er tydelig på at et Maskinporten-token må valideres og byttes ut før de API-ene kalles. Grunnen er praktisk framfor seremoniell. Altinn-tokenet bærer claims plattformen trenger og som Maskinporten ikke utsteder, som organisasjonsnummeret i Altinns egne felter og et autentiseringsnivå, og plattformens autorisasjonsregler er skrevet mot de claimene.

Avgjørelsesregelen er derfor kort: slå opp hvilken flate du integrerer mot før du skriver token-rørleggingen. Er det Dialogporten eller en annen flate som er dokumentert å godta Maskinporten-token, er du ferdig etter det første token-kallet. Er det en app eller et plattform-API, sett av tid til vekslingen som beskrives under. Det bredere spørsmålet om hvordan Maskinporten-leddet selv virker, med sertifikater, assertions og mellomlagring, eies av autentiseringsveiledningen, og denne siden forutsetter at det leddet allerede virker.

Hvordan fungerer vekslingskallet?

Det er ett GET-kall. Du kaller /authentication/api/v1/exchange/maskinporten på Altinn-plattformens vert for miljøet ditt, med Maskinporten-tokenet i Authorization: Bearer-headeren og ingenting annet. Endepunktet validerer det innkommende tokenet og utsteder et nytt JWT signert av Altinn. I testmiljøet er verten platform.tt02.altinn.no; i produksjon er den platform.altinn.no. Miljøene er separate tillitsdomener, og det er viktig for feilmodusene nedenfor.

Utgangstokenet er verdt å lese én gang i en debugger, fordi det forklarer hvorfor vekslingen finnes. Scopene dine kopieres over uendret, så vekslingen utvider eller innsnevrer aldri hva du kan gjøre. Oppå dem legger konverteringen til organisasjonsfeltene Altinn løser opp for deg, og claimet AuthenticationLevel. Det claimet er det det rå Maskinporten-tokenet ikke bærer, og det er det autorisasjonsregler som krever et minste autentiseringsnivå evaluerer.

Behandle resultatet som en kortlevd legitimasjon i samme løkke som Maskinporten-tokenet som produserte det. Utsted, veksle, mellomlagre til like før utløp, gjenta. Ingenting ved vekslingen er en engangsregistrering, og ingenting lagres på tjenersiden mellom kall: har du et gyldig Maskinporten-token, kan du alltid utstede et ferskt Altinn-token fra det. Den samme klokkedisiplinen som assertion-steget trenger, gjelder her, siden et utløpt inngangstoken stryker i vekslingen framfor å forringes pent.

Hvorfor avvises et direkte systembruker-token?

Dette er feilen som koster integratører mest tid, fordi hvert enkelt steg ser riktig ut. Du har et gyldig Maskinporten-token for en systembruker, delegeringen finnes, scopene stemmer, og API-et svarer likevel med en autorisasjonsfeil. Den manglende biten er som regel ikke myndighet, men informasjon: autorisasjonspunktet evaluerer claims på tokenet det får, og et rått Maskinporten-token bærer ikke autentiseringsnivå-claimet som det vekslede Altinn-tokenet gjør.

Når en regel krever et minste autentiseringsnivå og tokenet ikke presenterer noe, avvises forespørselen selv om den underliggende delegeringen er gyldig. Utenfra leses det som en rettighetsfeil, og team svarer med å ettergå delegeringer som aldri var ødelagt. Reparasjonen er mekanisk: send tokenet gjennom vekslingsendepunktet først, og gjør det vekslede tokenet til det eneste Altinn-klienten din noen gang fester på app- og plattformkall.

Ser du 403- eller 500-svar rundt systembruker-forespørsler mer generelt, har godkjenningsfeil, delegeringskontroller og liste-endepunkter sin egen feilklynge, og feilsøkingsveiledningen for systembrukere følger hvert symptom til årsaken. Den token-formede delmengden av de feilene løses her; den delegeringsformede løses der.

Gjør det første kallet

Curl-kallet under er selve vekslingen, i TT02, gitt at du allerede har et Maskinporten-token. TypeScript-eksempelet er den meglede ruten: én Apier-nøkkel, en dry-run-handling, og token-avgjørelsen tatt på den andre siden av kallet.

# Selve vekslingen, i testmiljøet TT02. Ett GET-kall,
# Maskinporten-tokenet som Bearer, et Altinn-JWT tilbake.
curl -s https://platform.tt02.altinn.no/authentication/api/v1/exchange/maskinporten \
  -H "Authorization: Bearer $MASKINPORTEN_TOKEN"

// Den meglede ruten: Apier avgjør hvilket token oppstrømskallet
// trenger, så koden din sender én nøkkel og ser aldri noe token.
const res = await fetch(
  "https://www.apier.no/api/v1/actions/execute?dry_run=true",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      Authorization: `Bearer ${process.env.APIER_API_KEY}`,
    },
    body: JSON.stringify({
      org_number: "999999999",
      action_type: "mva_melding",
      period: "2026-T1",
      payload: {},
    }),
  },
);

if (!res.ok) {
  // Alle ikke-2xx-svar bruker den samme strukturerte konvolutten.
  const { error_code, explanation } = await res.json();
  throw new Error(`${error_code}: ${explanation.summary}`);
}

const { data } = await res.json();
console.log(data.outcome.all_passed, data.outcome.checks);

Ofte stilte spørsmål

Er et Altinn-token en annen legitimasjon enn Maskinporten?

Det er samme identitet, utstedt på nytt. Vekslingsendepunktet validerer Maskinporten-tokenet ditt og utsteder et nytt JWT som kopierer scopene og legger til Altinn-spesifikke claims, blant annet organisasjonsnummeret og et autentiseringsnivå. Du søker aldri om et Altinn-token separat; du avleder det alltid fra et Maskinporten-token du allerede har.

Hvilke Altinn-API-er godtar et Maskinporten-token direkte?

Dialogporten gjør det: et sluttbrukersystem kan presentere et Maskinporten-token som identifiserer en systembruker, og tjenesteeier-systemer bruker Maskinporten-token der vekslingen er et valg framfor et krav. Altinn-apper og de klassiske plattform-API-ene er motsatt tilfelle: de forventer Altinn-tokenet fra vekslingsendepunktet, ikke det rå Maskinporten-tokenet.

Hvorfor svarer selve vekslingskallet med 401?

Vekslingen validerer det innkommende tokenet før den utsteder noe, så en 401 der betyr at Maskinporten-tokenet strøk i valideringen. De vanligste årsakene er et token som allerede er utløpt, siden Maskinporten-token lever i minutter, eller et token utstedt i ett miljø og presentert i et annet, siden test og produksjon stoler på ulike utstedere.

Kan jeg veksle én gang og beholde Altinn-tokenet?

Nei. Altinn-tokenet arver en kort levetid, så behandle vekslingen som en del av token-løkken framfor et engangsoppsett: utsted et Maskinporten-token, veksle det, mellomlagre resultatet til like før utløp, og kjør løkken på nytt. Den samme mellomlagringsdisiplinen som gjelder Maskinporten-token, gjelder det vekslingen returnerer.

Eksponerer Apier vekslingen for meg?

Nei, den fjerner hele avgjørelsen. Applikasjonen din autentiserer seg mot Apier med én API-nøkkel. Når en forespørsel trenger et offentlig oppstrøms-API, holder Apier-siden Maskinporten-klienten, utfører den vekslingen mål-API-et krever, og sender riktig token. Koden din kan ikke velge feil token, fordi den aldri velger token i det hele tatt.