What is Maskinporten?

Maskinporten and Altinn are national common components developed and operated by the Norwegian Digitalisation Agency (Digitaliseringsdirektoratet - Digdir). Together, they aim to facilitate the sharing and utilization of data across systems. These solutions ensure the verification of the identity of businesses and provide them with the appropriate access to data offered by public entities through interfaces. A prerequisite for using Maskinporten and Altinn is that the organization is registered in the Norwegian Business Registry (Enhetsregisteret) with a Norwegian organization number.

Maskinporten is a solution provided by the Norwegian Digitalisation Agency (Digdir) for access management for businesses that exchange data. The solution ensures identity assurance between organizations and provides authentication for machine-to-machine communication. It enables the integration of systems and the development of new services in an efficient manner.

In the future: Altinn (authorization) will allow for the delegation of rights to other organizations or individuals. This delegation is based on registered roles in the Norwegian Business Registry (Enhetsregisteret). This is not yet implemented.

Maskinporten ensures secure authentication and access control for data exchange between businesses. The solution guarantees the identity between organizations and enables the integration of systems and development of new services in an efficient manner.

Operations and monitoring

Maskinporten aims to maintain an uptime of 99.9% and, in case of any deviations, it rarely experiences downtime exceeding 5 minutes. Therefore, we recommend that our clients implement a retry mechanism to try again if messages are rejected without clear error messages.

We further recommend monitoring both planned and unplanned operational disruptions:

It is also possible to verify if Maskinporten is up by using the links below:

Maskinporten has also created a troubleshooting page at https://docs.digdir.no/docs/Maskinporten/maskinporten_feilsoking.

What is needed to use Maskinporten?

The guide below is in line with Maskinporten's own documentation, https://docs.digdir.no/docs/Maskinporten/maskinporten_guide_apikonsument. See also Digdir's guide on how to get started with Maskinporten: https://samarbeid.digdir.no/maskinporten/konsument/119

Prerequisite: Norwegian organization number

It is a prerequisite for using Maskinporten that you are registered in the Norwegian Central Coordinating Register of Legal Entities (Enhetsregisteret) with a Norwegian organization number.

1. Acquire a company certificate for testing and production purpose

Digdir will validate your signature against your organization's certificate issued by a recognized certificate provider. Find more documentation on this processat Digdir.

Here are some options for acquiring an organization certificate:

2. Establish account at Digdir to access the self-service portal (Samarbeidsportalen)

Contact Digdir via servicedesk@digdir.no

3. Register at Norwegian Customs

You can find a registration form here: Registration: Digitoll-users – Norwegian Customs

Tolletaten provides access to the scopes required for the specific integration, see overview below.

4. Create an integration with Digdir and connect it to Norwegian Customs API (scope)

Logg deg inn på Samarbeidsportalen (digdir.no)

4.1 Go to self service

See caption
Figure: Go to self-service
See caption
Figure: Choose environment

To manage integrations for testing: Select "Integrations" under the heading "Ver 2"
To manage integrations for production: Select "Integrations" under the heading "Produksjon"

4.2 Create an integration in the Ver2 environment at Digdir.

See caption
Figure: Go to integrations

4.3 Create an integration in the PRODUKSJON environment at Digdir

See caption
Figure: Go to integrations

4.4 New integration

See caption
Figure: Click new integration.
Se See caption
Figure: Filling in the fields

5. Client integration

API consumers must develop their own application/system that retrieves access tokens from Maskinporten and exchanges them for access tokens signed by Norwegian Customs.

TIP:
Access tokens signed by Norwegian Customs can be used throughout its lifetime, so it is recommended to cache them when communicating with the APIs. For a smoother experience, it is further recommended to exchange it for a new token before (e.g., 1 minute before) the expiration of the previous one.

5.1 Get access token from Maskinporten

See Maskinportens own documentation on how to get an access token.

TIP:
Digdir has published a repository on github (jwt-grant-generator) which demonstrates how to get an access token from Digdir's services, for example from Maskinporten.

5.2 Exchange Maskinporten access token to an access token signed by Norwegian Customs

HTTP Request

Method: POST

URL:

Environment URL
Test https://api-test.toll.no/api/access/external/oauth/token
Production https://api.toll.no/api/access/external/oauth/token

HEADER:

Header Value
Content-type application/x-www-form-urlencoded

BODY:

Key Value
grant_type token-exchange
subject_token_type access_token
subject_token <MASKINPORTEN ACCESS TOKEN HERE>
Example: HTTP Response

Maskinporten Access Token - Response

{
    "issued_token_type": "access_token",
    "access_token": "<TOLL ACCESS TOKEN HER>"
    "token_type": "Bearer",
    "expires_in": 970
}
        

5.3 Test access to the API

This example applies to the API for road vehicles.

HTTP Request

Method: GET

URL:

Environment URL
Test https://api-test.toll.no/api/movement/road/v1/test-auth
Production https://api.toll.no/api/movement/road/v1/test-auth

HEADER:

Header Value
Authorization Bearer <TOLL ACCESS TOKEN>

Expected result is 200 OK.

Our scopes

Which scope(s) you should use depend on the specific services you intend to use, and it requires granted access to that scope from Norwegian Customs:

movement-road-api:
toll:movement/road
movement-road-api-v2,
movement-road-query-api-v2:
toll:movement/road/v2
movement-air-api,
movement-air-query-api:
toll:movement/air
movement/presentation,
movement/routing:
toll:movement/entry
Document upload:
toll:goodsdeclaration/document.write