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
Structure the JSON payload Prepare a JSON payload to be sent to the API. Below is a detailed description of the fields.
Define Identifiers
id: A unique identifier for the system.- Format:
{systemVendorOrgNo}_{chosenName}. - Example:
991825827_smartcloud.
- Format:
vendor: Contains the organization number of the system vendor.- Format:
IDmust be set to0192:{orgnr}to specify reference to the Brønnøysund Register Centre. - Example:
"ID": "0192:991825827".
- Format:
- Important: The organization number used in
idandvendor.IDmust match the organization number in the authentication token (Maskinporten or Altinn).
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), anden(English).
Define Rights (
rightsandaccessPackages)- Specify which services or access packages the system requires access to.
- Use
rightsto specify individual resources (e.g.,urn:altinn:resource). - Use
accessPackagesto 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.
Link Client ID (
clientId)- Provide a list of
clientIdvalues (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.
- Provide a list of
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.
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).
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 }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
isVisibleis set totrue, the system will also be visible in the Altinn portal. - Modification: Systems that are registered can be modified and deleted afterwards via the API.