Hvordan setter jeg opp en systembruker i Altinn, fra registrering til første token?

Steg 1: hva må registreres før noen kunde kan godkjenne?

Forutsetningen er en egen Maskinporten-klient, fordi systemet du skal registrere, delvis defineres av klienten det autentiserer seg som. Med den på plass oppretter du en oppføring i Altinns systemregister. Oppføringen bærer virksomhetens organisasjonsnummer på ISO 6523-form, navn og beskrivelse på bokmål, engelsk og nynorsk, rettighetene og tilgangspakkene systemet ber kundene om, klientidentifikatorlisten fra Maskinporten, og eventuelt omdirigeringsadresser og et synlighetsflagg som avgjør om kunder kan finne systemet ved navn.

Registreringskallet er selv et kall mellom maskiner: det er beskyttet av skrivescopet for systemregisteret, så Maskinporten-klienten din må ha det scopet innvilget før registreringen kan skje. Dette er steget der den offisielle dokumentasjonen er mest spredt, fordi klienten hører hjemme i Digdirs verden og registeret i Altinns, og hver side dokumenterer sin egen halvdel.

Valget som betyr mest her, er pakkelisten. Oppsettveiledningen er tydelig på at leverandøren har ansvaret for å registrere de riktige tilgangspakkene, og alt nedstrøms arver beslutningen: kunden godkjenner nøyaktig det registeroppføringen ber om, en for bred liste får godkjenninger til å nøle, og en for smal feller senere kall. Hvilken legitimasjonskonstruksjon som spiller hvilken rolle i denne kjeden, eies av veiledningen om valg av legitimasjon.

Steg 2: hva ser kunden, og hvem godkjenner?

For hver kunde oppretter du en systembrukerforespørsel som navngir pakkene det registrerte systemet ditt ber om. Svaret bærer en godkjenningslenke; ta vare på den når du først mottar den, for en gjentatt oppretting av samme forespørsel er observert å svare uten den. Kunden åpner lenken, logger inn i Altinn, og ser systemet ditt under det registrerte navnet sammen med pakkene det ber om, beskrevet i forretningstermer i stedet for som rå scopes.

Godkjenningen er selv en delegering, og det avgjør hvem som kan utføre den. Kontrollen er alt eller ingenting: godkjenneren må ha myndighet til å delegere hver pakke i forespørselen, så én sensitiv pakke kan felle en godkjenning en daglig leder ellers kunne gitt. Når en godkjenning feiler med 403, eller en 500 som oppfører seg som en, eies årsakene og løsningene symptom for symptom av feilsøkingsveiledningen for systembrukere, som denne gjennomgangen med vilje ikke gjentar.

Én egenskap ved resultatet er verdt å designe for fra dag én. Oppsettveiledningen sier rett ut at Altinn ikke vet hvem den enkelte brukeren bak systembrukeren er: tildelingen navngir systemet ditt, ikke de ansatte dine. Den kontrollen per bruker produktet ditt trenger oppå den delegerte myndigheten, er din å bygge, og å late som plattformen leverer den er et etterlevelsesgap som venter på å bli synlig.

Steg 3 og 4: hvordan får jeg tokenet og gjør det første kallet?

Tokenforespørselen går til Maskinporten, med det samme signerte JWT-grantet klienten din allerede bruker, med ett tillegg: en authorization_details-oppføring av typen urn:altinn:systemuser der systemuser_org navngir kundens organisasjonsnummer på ISO 6523-form, organisasjonsnummeret bak et 0192:-prefiks. I testmiljøet går forespørselen til tokenendepunktet på test.maskinporten.no; en valgfri externalRef peker forespørselen mot én bestemt systembruker når kunden har opprettet flere.

Det som kommer tilbake, er det som skiller systembrukertokenet fra et vanlig Maskinporten-token. Scopene er de samme, men tokenet som utstedes, bærer et authorization_details-claim med systembrukeridentifikator og din systemidentifikator, som er slik API-et som mottar kallet, avgjør at klienten din opptrer under kundens delegerte myndighet og ikke sin egen. Claimet utvider ikke hva du kan gjøre; det endrer hvems myndighet kallet bærer.

Siste steg er selve kallet, og det har én forgrening: noen Altinn 3-flater godtar Maskinporten-tokenet direkte, mens Altinn-apper og de klassiske API-ene på plattformen krever at det først veksles til et Altinn-token. Den beslutningen, og selve vekslingskallet, eies av veiledningen om tokenveksling. For testing kjører du hele kjeden i testdomenet: Maskinportens testmiljø utsteder tokenet, og TT02, på platform.tt02.altinn.no, evaluerer delegeringen. De to miljøene er atskilte tillitsdomener, så ingenting bevist i det ene følger med inn i det andre.

Gjør det første kallet

Sandkassekallet svarer på hvem som overhodet kan opptre for et selskap, uten nøkkel. TypeScript-eksempelet er oppslaget som hører hjemme før steg to: de registrerte signatarene for kundeselskapet, fra Brønnøysund, så du vet hvem sin godkjenning som passerer kontrollen som godtar alt eller ingenting. Hvert steg i selve sekvensen, registrering, godkjenning og token, kjører på din egen klient mot Altinn; Apier formidler ingen del av det.

# Nøkkelløs sandkasse: hvem som kan opptre for et selskap, fra registeret.
curl -s https://www.apier.no/api/v1/sandbox/public/company/999999999/authority

// Før steg 2: hvem som kan godkjenne, fra Brønnøysund, med én Apier-nøkkel.
// Selve sekvensen (registrere, godkjenne, token) kjører på din egen klient.
// 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

Hva må være på plass før jeg kan registrere et system?

En egen Maskinporten-klient, fordi oppføringen i systemregisteret kobler systemet til klientidentifikatorene det skal autentisere seg som, og selve registreringskallet er beskyttet av skrivescopet for systemregisteret. Oppføringen bærer så virksomhetens organisasjonsnummer, navn og beskrivelse på tre språk, rettighetene og tilgangspakkene systemet ber om, og eventuelt omdirigeringsadresser og et synlighetsflagg.

Hvem hos kunden kan godkjenne systembrukerforespørselen?

Noen hvis egen myndighet dekker hver pakke forespørselen navngir. Godkjenningen er selv en delegering, og kontrollen er alt eller ingenting: godkjenneren må kunne delegere samtlige pakker, så én pakke utenfor myndigheten feller hele godkjenningen. Registerroller som daglig leder dekker de fleste pakkene; de sensitive krever virksomhetens hovedadministrator.

Hva skiller et systembrukertoken fra et vanlig Maskinporten-token?

Claimet authorization_details. Et vanlig token bekrefter din organisasjon og dens scopes. Et systembrukertoken bes om med en authorization_details-oppføring som navngir kundens organisasjon, og tokenet som utstedes bærer systembrukeridentifikator og systemidentifikator tilbake til deg, som er det API-et bruker for å avgjøre hvilken myndighet kallet opptrer under. Scopene utvides ikke av dette.

Hvordan kjører jeg hele sekvensen i et testmiljø?

Bruk testkjeden fra ende til ende: testmiljøet til Maskinporten utsteder tokenet, og TT02, Altinns testmiljø på platform.tt02.altinn.no, evaluerer delegeringen. Test og produksjon er atskilte tillitsdomener, så ingenting følger med over: verken systemregistreringen, kundens godkjenning eller tokenet. En sekvens bevist i TT02 må etableres på nytt, del for del, i produksjon.

Finnes det en snarvei gjennom Apier?

Nei. Apier holder ingen systemregistrering eller Maskinporten-klient på dine vegne og formidler ikke delegeringen; fullmaktsendepunktene Apier tidligere tilbød ble trukket tilbake 21. oktober 2026 og svarer 410 CAPABILITY_WITHDRAWN. Det Apier svarer på, er spørsmålet før steg to: hvem i kundeselskapet som kan godkjenne, som signaturrett og prokura fra Brønnøysund, slik at godkjenningslenken når en person med myndighet som dekker hver pakke.