Skip to content
Apier

Utvikler-API

Altinn System User-API

Slik delegerer en virksomhet tilgang til et system — ikke en person — i Altinn 3, og slik handler Apier på vegne av den bak én Bearer-nøkkel. Dette er System User-flyten spesifikt, ikke generell Altinn-integrasjon.

Les System User-guidenPrøv sandkassen

Hva er en Altinn System User?

En System User (systembruker) i Altinn 3 er måten en virksomhet delegerer tilgang til et programvaresystem på, i stedet for til en navngitt person. Apier registrerer systemet i Altinn System Register; virksomheten godkjenner systembrukeren og delegerer de nødvendige ressursene (tilgangspakker), og Apier handler deretter på vegne av virksomheten med den tilgangen.

En systembruker lar integrasjonen fortsette å virke selv om personen som opprinnelig satte den opp slutter — tilgangen er knyttet til systemet, ikke til et personlig Altinn-login. Det er nettopp derfor en virksomhet delegerer til en systembruker når en programvare skal handle på vegne av den over tid, og ikke til en navngitt ansatt-bruker.

For generell Altinn 3-integrasjon — skjemaer, instanser og hele plattformen — se Altinn-API-siden. Denne siden dekker kun systembruker-delegeringen.

Hvordan autentiserer en System User seg?

System User-flyten hviler på Maskinporten: Apier presenterer en signert JWT-client-assertion backet av virksomhetssertifikatet, får et Maskinporten-token med riktige scopes, og bruker det sammen med systembruker-delegeringen mot Altinn. Du autentiserer mot Apier med én Bearer-API-nøkkel — token-vekslingen skjer server-side.

Sertifikat-, JWK- og rotasjonsdetaljene bak Maskinporten-tokenet er beskrevet på Maskinporten-API-siden.

Hvordan delegerer en virksomhet til en System User?

Oppsettet har tre ledd: en Maskinporten-klient (auth), en systemregistrering i Altinn System Register (via Samarbeidsportalen), og virksomhetens godkjenning av systembrukeren med konkrete tilgangspakker. Når virksomheten har godkjent delegeringen i Altinn, kan Apiers Auth Gateway autorisere kall på vegne av den. Delegeringen er tidsavgrenset og kan trekkes tilbake av virksomheten når som helst.

  • Maskinporten-klient — auth-leddet som beviser hvem systemet er.
  • Altinn System Register — systemregistreringen via Samarbeidsportalen.
  • Virksomhetens godkjenning — virksomheten delegerer konkrete tilgangspakker til systembrukeren i Altinn.

Hvordan kommer jeg i gang?

Les guiden Altinn System Users for hele oppsettet, og verifiser delegeringen før du sender bindende handlinger: kall GET /api/v1/auth/permissions/{org} for å se delegeringssnapshotet ditt for virksomheten. I sandkassen står syntetiske fixtures inn for en innvilget delegering, så du kan bygge integrasjonen før delegeringen er på plass i produksjon.

  1. Registrer systemet i Altinn System Register via Samarbeidsportalen, og koble det til Maskinporten-klienten.
  2. Be virksomheten godkjenne systembrukeren og delegere de nødvendige tilgangspakkene i Altinn.
  3. Provisjonér en API-nøkkel med read:altinn-scope, og bekreft delegeringen ved å lese delegeringssnapshotet for virksomheten.
  4. Bygg og test mot sandkasse-speilet før delegeringen er på plass i produksjon — syntetiske fixtures står inn for en innvilget delegering.

Hvordan håndterer jeg manglende delegering og feil?

Mangler delegeringen, svarer Altinn 403 og Apier returnerer en AUTH_NO_DELEGATION-handover som forklarer hvem som må delegere, hvor (i Altinn) og hvorfor agenten ikke kan fortsette. Andre vanlige feil er SCOPE_INSUFFICIENT (nøkkelen mangler read:altinn-scope) og MASKINPORTEN_TOKEN_FAILED (token-veksling feilet, som regel forbigående). Alle feil følger Compliance Explainer-formatet med norsk forklaring og fix_steps.

  • 403 AUTH_NO_DELEGATION — virksomheten har ikke delegert til systembrukeren; handoveren forklarer hvem som må delegere, hvor og hvorfor.
  • 403 SCOPE_INSUFFICIENT — API-nøkkelen mangler read:altinn-scope.
  • 502 MASKINPORTEN_TOKEN_FAILED — token-vekslingen feilet; som regel forbigående.

Kodeeksempel

Verifiser delegeringen før du sender bindende handlinger ved å lese delegeringssnapshotet for virksomheten.

# Delegeringssnapshot: hva har virksomheten delegert til systembrukeren din?
curl -H "Authorization: Bearer $APIER_API_KEY" \
  "https://www.apier.no/api/v1/auth/permissions/999999999"
# Null-auth sandkasse — syntetisk virksomhet 999999999.
curl "https://www.apier.no/api/v1/sandbox/public/company/999999999/context"

Hvor finner jeg API-referansen?

Den fullstendige API-referansen ligger i OpenAPI 3.1-spesifikasjonen på /openapi.json og i utviklerdokumentasjonen under /docs/api. Hele System User-oppsettet steg for steg er beskrevet i guiden /docs/guides/altinn-system-users.

Relaterte utviklersider