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 tjenesteeiersystemer bruker Maskinporten-token der vekslingen er en mulighet framfor en plikt.

Den klassiske plattformen er den andre halvdelen av skillet. Altinn-apper og API-ene på plattformen 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 tokenrørleggingen. Er det Dialogporten eller en annen flate som er dokumentert å godta Maskinporten-token, er du ferdig etter det første tokenkallet. Er det en app eller et API på plattformen, 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 assertionsteget trenger, gjelder her, siden et utløpt inngangstoken stryker i vekslingen framfor å forringes pent.

Hvorfor avvises et direkte systembrukertoken?

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å appkall og plattformkall.

Ser du 403- eller 500-svar rundt systembrukerforespørsler mer generelt, har godkjenningsfeil, delegeringskontroller og listeendepunkter sin egen feilklynge, og feilsøkingsveiledningen for systembrukere følger hvert symptom til årsaken. Den tokenformede 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 oppslaget som ikke trenger noen av tokenene: én Apier-nøkkel, de registrerte signatarene for et selskap, og ingen veksling noe sted i 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"

// Det som ikke trenger noen av tokenene: hvem som kan signere for
// selskapet, fra Brønnøysund, med én Apier-nøkkel. Vekslingen over er din.
// Bytt ut {org} med et ekte organisasjonsnummer; 999999999 finnes bare i sandkassen.
const res = await fetch("https://www.apier.no/api/v1/company/{org}/authority", {
  headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` },
});

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, _meta } = await res.json();
// "sole" | "joint" | "by_role" | "prokura_only" | "no_authority" | "unknown"
console.log(data.classification, data.summary, _meta.data_source);

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 tjenesteeiersystemer bruker Maskinporten-token der vekslingen er et valg framfor et krav. Altinn-apper og de klassiske API-ene på plattformen 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 tokenlø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.

Gjør Apier vekslingen for meg?

Nei. Apier kaller ikke Altinn eller Maskinporten på dine vegne og har ingen klient for vekslingen; de Altinn-baserte endepunktene Apier tidligere tilbød ble trukket tilbake 21. oktober 2026 og svarer 410 CAPABILITY_WITHDRAWN. Avgjørelsen på denne siden er din å ta i din egen klient. Det Apier svarer på, trenger ingen av tokenene: hvem som kan signere for et selskap, fra Brønnøysund, og hva det må sende inn innen når, fra regelboken.