Last modified: Oct 27, 2025

System Registration

This guide describes how you, as an end-user system vendor, register a system in the system registry.

Target Audience: Developers or technical integration managers at end-user system vendors (SBS).

Prerequisites

Before you can register a system, the following must be in place:

  • Access to the system registry and system user scopes has been obtained from Digdir. The procedure for this is described on the Cooperation Portal (Samarbeidsportalen).
  • For testing, it is recommended that the SBS organization number is added to the TT02 test environment.
  • To get a real organization number created in TT02, the SBS must contact servicedesk@altinn.no.
  • An overview of which access packages (accessPackages) or resources (rights) the service API requires. This information must be obtained from the service owner.
  • One or more valid clientId (UUID) generated for the integration in Maskinporten.
  • A valid Maskinporten token or Altinn token to authenticate the API call to the system registry.

Instructions

Registration of an end-user system is done by calling Altinn’s system registry API with a JSON payload that defines the system.

Step-by-step

  1. Structure the JSON payload Prepare a JSON payload to be sent to the API. Below is a detailed description of the fields.

  2. Define Identifiers

    • id: A unique identifier for the system.
      • Format: {systemVendorOrgNo}_{chosenName}.
      • Example: 991825827_smartcloud.
    • vendor: Contains the organization number of the system vendor.
      • Format: ID must be set to 0192:{orgnr} to specify reference to the Brønnøysund Register Centre.
      • Example: "ID": "0192:991825827".
    • Important: The organization number used in id and vendor.ID must match the organization number in the authentication token (Maskinporten or Altinn).
  3. Define Visible Texts

    • Specify the name and description to be displayed for the system in the Altinn portal.
    • Texts must be provided for all supported languages: nb (Bokmål), nn (Nynorsk), and en (English).
  4. Define Rights (rights and accessPackages)

    • Specify which services or access packages the system requires access to.
    • Use rights to specify individual resources (e.g., urn:altinn:resource).
    • Use accessPackages to specify predefined access packages (e.g., urn:altinn:accesspackage:skattegrunnlag).
    • Note: These rights must be defined correctly before a system user can be created for this system.
  5. Link Client ID (clientId)

    • Provide a list of clientId values (as UUIDs) that are generated in Maskinporten for this integration.
    • A system can be linked to multiple client IDs.
    • This is the same client ID that will later be used when creating a system user towards Maskinporten.
  6. Set Visibility (isVisible)

    • true: The system is visible in the Altinn portal and can be used to create a system user from there.
    • false: The system is not visible in the portal. In this case, the system user must be created through a vendor-controlled process.
  7. Specify Redirect URLs (allowedredirecturls)

    • Define a list of exact URLs that are approved for redirection in the system user creation flow. A system user request must use a URL from this list (or a subset).
  8. Example JSON Payload Use the following structure as a template for your JSON payload:

    {
      "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 the API call

    • Execute a POST or PUT request (for creation or modification) to Altinn’s system registry API with the JSON payload.
    • Remember to include your Maskinporten or Altinn token in the Authorization header for authentication.

Verification and Notes

  • Verification: After successful registration, the system will be available for creating system users. If isVisible is set to true, the system will also be visible in the Altinn portal.
  • Modification: Systems that are registered can be modified and deleted afterwards via the API.