Sist endret: 30. okt. 2025

Registrering av system

Denne veiledningen beskriver hvordan du som sluttbrukersystemleverandør registrerer et system i systemregisteret.

Målgruppe: Utviklere eller tekniske integrasjonsansvarlige hos sluttbrukersystemleverandører (SBS).

Forutsetninger

Før du kan registrere et system, må følgende være på plass:

  • Tilgang til systemregisteret og systembruker-scopes er innhentet fra Digdir. Prosedyren for dette er beskrevet på Samarbeidsportalen.
  • For testing anbefales det at SBS-organisasjonsnummeret er lagt inn i testmiljøet TT02.
  • For å få opprettet et ekte organisasjonsnummer i TT02, må SBS kontakte servicedesk@altinn.no.
  • Et gyldig Maskinporten-token eller Altinn-token for å autentisere API-kallet mot systemregisteret.
  • Tokenet som benyttes må ha blitt tildelt scopet: altinn:authentication/systemregister.write.
  • En oversikt over hvilke tilgangspakker (accessPackages) eller ressurser (rights) tjeneste-API-et krever. Denne informasjonen må innhentes fra tjenesteeier.
  • En eller flere gyldige clientId (UUID) generert for integrasjonen i Maskinporten.

Instruksjoner

Registrering av et sluttbrukersystem gjøres ved å kalle Altinns systemregister-API med en JSON-nyttelast som definerer systemet.

Steg-for-steg

  1. Strukturér JSON-nyttelasten Klargjør en JSON-nyttelast (payload) som skal sendes til API-et. Nedenfor følger en detaljert beskrivelse av feltene.

  2. Definer Identifikatorer

    • id: En unik identifikator for systemet.
      • Format: {systemleverandørorgnr}_{valgt navn}.
      • Eksempel: 991825827_smartcloud.
    • vendor: Inneholder organisasjonsnummeret til systemleverandøren.
      • Format: ID må settes til 0192:{orgnr} for å angi referanse til Enhetsregisteret.
      • Eksempel: "ID": "0192:991825827".
    • Viktig: Organisasjonsnummeret som brukes i id og vendor.ID må samsvare med organisasjonsnummeret i autentiseringstokenet (Maskinporten eller Altinn).
  3. Definer Synlige Tekster

    • Angi navn og beskrivelse som skal vises for systemet i Altinn-portalen.
    • Tekster må oppgis for alle støttede språk: nb (bokmål), nn (nynorsk) og en (engelsk).
  4. Definer Rettigheter (rights og accessPackages)

    • Angi hvilke tjenester eller tilgangspakker systemet krever tilgang til.
    • Bruk rights for å spesifisere individuelle ressurser (f.eks. urn:altinn:resource).
    • Bruk accessPackages for å spesifisere forhåndsdefinerte tilgangspakker (f.eks. urn:altinn:accesspackage:skattegrunnlag).
    • Merk: Disse rettighetene være definert korrekt før en systembruker kan opprettes for dette systemet.
  5. Knytt Klient-ID (clientId)

    • Oppgi en liste med clientId-verdier (som UUIDs) som er generert i Maskinporten for denne integrasjonen.
    • Et system kan være knyttet til flere klient-ID-er.
    • Dette er den samme klient-ID-en som senere skal brukes ved opprettelse av systembruker mot Maskinporten.
  6. Angi Synlighet (isVisible)

    • true: Systemet er synlig i Altinn-portalen og kan benyttes for å opprette en systembruker derfra (brukerstyrt opprettelse).
    • false: Systemet er ikke synlig i portalen. Systembruker må i dette tilfellet opprettes gjennom en leverandørstyrt prosess.
    • Viktig: Et system kan ikke settes til isVisible: true dersom det samtidig har IsAssignable: false (et felt som styrer tildelbarhet, ikke vist i JSON-eksempelet).
  7. Angi Omdirigerings-URLer (Valgfritt) (allowedredirecturls)

    • Dette feltet er valgfritt og kan utelates eller settes som en tom liste ([]).

    • Hvis feltet benyttes, må det inneholde en liste over nøyaktige URL-er som er godkjent for omdirigering i flyten for opprettelse av systembruker.

    • Dersom listen er definert, må en systembrukerforespørsel bruke en URL fra denne listen (eller et subsett av den).

  8. Eksempel på JSON-nyttelast Bruk følgende struktur som mal for din JSON-nyttelast:

    {
      "id": "991825827_smartcloud",
      "vendor": {
        "authority": "iso6523-actorid-upis",
        "ID": "0192:991825827"
      },
      "name": {
        "nb": "SmartCloud 1",
        "en": "SmartCloud 1",
        "nn": "Smart SKY"
      },
      "description": {
        "nb": "SmartCloud er verdens beste system.",
        "en": "SmartCloud Rocks.",
        "nn": "SmartSky er vestlandets beste system"
      },
      "rights": [
        {
          "resource": [
            {
              "id": "urn:altinn:resource",
              "value": "ske-krav-og-betalinger"
            }
          ]
        }
      ],
      "accessPackages": [
        {
          "urn": "urn:altinn:accesspackage:skattegrunnlag"
        }
      ],
      "clientId": ["32ef65ac-6e62-498d-880f-76c85c2052ae"],
      "allowedredirecturls": ["https://smartcloudxxxx/receipt"],
      "isVisible": true
    }
    
  9. Send API-kallet

    • Bruk en POST-forespørsel for å opprette systemet første gang.

    • Bruk en PUT-forespørsel for å endre et eksisterende system.

    • VIKTIG: En PUT-forespørsel overskriver hele systemdefinisjonen. Når du skal endre (f.eks. legge til en ny tilgangspakke), må du hente den eksisterende definisjonen, gjøre endringene, og deretter sende hele den oppdaterte JSON-nyttelasten i PUT-kallet. Hvis du kun sender de nye endringene, vil all tidligere informasjon bli slettet.

    • Inkluder alltid ditt gyldige Maskinporten- eller Altinn-token i Authorization-headeren for autentisering.


Verifisering og Merknader

  • Verifisering: Etter vellykket registrering vil systemet være tilgjengelig for opprettelse av systembrukere. Hvis isVisible er satt til true, vil systemet også være synlig i Altinn-portalen.
  • Endring: Systemer som er registrert kan endres og slettes i etterkant via API-et.