What is Maskinporten?

Maskinporten and Altinn are national common components developed and operated by the Norwegian Digitalisation Agency (Digitaliseringsdirektoratet - Digdir).

Together, they aim to simplify the sharing and use of data across systems, for example by granting organizations appropriate access to data offered by public entities via interfaces. The solution guarantees identity between organizations and ensures authentication in machine-to-machine communication. It enables systems to be connected and new services to be developed efficiently.

To use Maskinporten, the organization must either be registered in the Norwegian Entity Registry with a Norwegian organization numberor possess an enterprise certificate listed on the EU’s “List of Trusted Lists.”

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:

Digdir Status - History at https://status.digdir.no/

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

Maskinporten has also created a troubleshooting page

What is needed to use Maskinporten?

The process differs for Norwegian and European organizations. The procedure for European organizations can be found here.

For Norwegian organizations

Guide aligned with Maskinporten’s official documentation

The guide below is in line with Maskinporten's own documentation

See also Digdir's guide on how to get started with Maskinporten:

Prerequisite: the organization has 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 process at Digdir.

Here are some options for acquiring an organization certificate:

2. Become a customer of Digdir for access to the collaboration portal

Contact Digdir via servicedesk@digdir.no

3. Register for access with Norwegian Customs

The registration form can be found here: Registration: Digitoll-actor - Norwegian Customs

Norwegian Customs provides access to the scopes needed for the relevant integration, see overview below.

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

For PROD: Log in to Self-service portal (digdir.no)

For TEST: Log in to Self-service portal (digdir.no)

Difi-service = Maskinporten
Add scopes – see overview of our scopes below
Integration identifier: This is what should be set in the "iss" field of your JWT sent to Difi (cf. section below).
Name of the integration: You are free to choose what the integration with Norwegian Customs should be called.
It may be beneficial to give a name that distinguishes between different services and APIs for Norwegian Customs, as we have several different APIs.
Grant-types: We currently use urn:ietf:params:oauth:grant-type:jwt-bearer, this may change in the future.

4.1 Go to self-service for integrations

Figure: Go to self-service — Figure: Login at self-service

Select client — Figure: For those integrating a service, select Client

4.2 New integration

Add new integration. — Figure: Here is a list of your clients. For a new client integration, click Add new.

Select Add scope — Figure: After entering your chosen name and description, click Add scope

Figure: Select the scopes you need, you can find an overview below

Overview of the integration — Figure: After clicking create, you will get an overview of your integrations/clients. Click the one you just created to see details and edit if needed.

5. Client Integration

API consumers must develop an application/system that retrieves access tokens from Maskinporten and exchanges them for Toll-signed access tokens.

TIPS:
A Toll-signed access token can be used for its entire lifetime, so it is recommended to cache these when communicating with Norwegian Customs' APIs. For a smoother experience, it is further recommended to exchange for a new Toll token before (e.g., 1 minute before) the lifetime of the previous one expires.

Our scopes

The scope(s) you should use depend on the services you will use and require assigned access to this 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

5.1 Retrieve access token from Maskinporten

See Maskinporten's own documentation on how to retrieve an access token.

TIPS:
Difi has published a repository on GitHub (jwt-grant-generator) that demonstrates how to retrieve access tokens from Difi's services, including Maskinporten.

5.2 Exchange Maskinporten's access token for a Toll-signed access token

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 HERE>",
  "token_type": "Bearer",
  "expires_in": 970
}

5.3 Test access to the API

This example applies to the road vehicle API.

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.

For European organizations

Requirement: The enterprise has an enterprise certificate listed on the EU’s “List of Trusted Lists.

European eSeals | Maskinporten , follow the guide for European organizations.

1. Obtain a valid European enterprise certificate

The client must have a valid electronic seal certificate issued by a qualified trust service provider listed on the EU Trusted List. Note that a listed provider typically offers multiple certificate services, which usually originate from different chains/roots, and just some of these chains/roots are in the trusted list.

2. Register for access with the Norwegian Customs (Tolletaten)

Registration form: Digitoll Registration – Tolletaten

Tolletaten grants access to the scope(s) required for the relevant integration. See the scopes below.

3. Client Integration

API consumers must develop an application/system that retrieves access tokens from Maskinporten and exchanges them for Toll-signed access tokens.

Our scopes

The scope(s) you should use depend on the services you will use and require assigned access to this scope from Norwegian Customs:

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

3.1 Retrieve access token from Maskinporten

See Digdir’s documentation under request European eSeals | Maskinporten

3.2 Retrieve access token from Maskinporten

Same procedure as for Norwegian organizations .

3.3 Retrieve access token from Maskinporten

Same procedure as for Norwegian organizations .