Last modified: May 28, 2024

Altinn Events API

An overview of the Altinn Events API

The Altinn Events API is an HTTP-based RESTful API that provides endpoints and actions for publishing of events and subscribing to events from Altinn 3 Apps and other registered sources.

Base URL

The following base urls correspond to each environment

  • AT (Private Altinn acceptance test environment)

    https://platform.{environment}.altinn.cloud/events/api/v1

  • TT02 (Application owner test environment)

    https://platform.tt02.altinn.cloud/events/api/v1

  • Production

     https://platform.altinn.cloud/events/api/v1

Authentication & Authorization

Altinn token

The Events API is secured using OAuth2 and all requests must include a valid Altinn token either in the Authorization header or in the AltinnStudioRuntime cookie.

For clients within the Altinn eco-system representing an external user or organization, the Altinn token in an incoming request can be forwarded to the Events API.

If you are using the API from an external system you will need to generate a Maskinporten or ID-Porten token and exchange this for an Altinn token before calling the Events API.

Below are two guides on how to achieve this.

Maskinporten scopes

Some endpoints in the API may require additional authorization in the form of a Maskinporten scope. A scope represents a permission that a consumer has access to.

You can connect a given set of scopes to the specific Maskinporten integration instance that provides your API client with Maskinporten tokens upon request.

Please reference Maskinporten’s own documentation on registering a new integration through their self service API.

Prerequisites

Register new integration through Samarbeidsportalen

  • Login to Samarbeidsportalen in Test or Production

  • Choose Selvbetjening and then Integrasjoner for the environment you want. Ver2 is test and Produksjon is production.

    “Samarbeidsportalen”
    Samarbeidsportalen

  • Choose Ny integrasjon

    “New integration”
    New integration

  • To fill out the form, provide all required properties:

    • Scopes: Choose Legge til scopes and include all the scopes necessary for the integration to generate tokens containing
    • Navn på integrasjonen: Add a descriptive name that allows you to identify the application that will be using the integration
    • Beskrivelse: Add a short description, not only for yourself but for everyone that administers integrations on behalf of your organization.

    “Add values for integration”
    Add values for integration

    The example above shows an integration used by an Altinn CLI Client which will need to generate tokens containing one or more of the three selected scopes; altinn:serviceowner, altinn:serviceowner/instances.read and altinn:serviceowner/instances.write

  • Choose Opprett in the top right corner when you have completed the configuration

The final steps of this guide cover creating a Json Web Key (JWK) for the integration to use to authenticate towards maskinporten, as well as noting down important values that can be used to configure the client that will integrate with Maskinporten.

Generate and register JWK for authentication towards Maskinporten

To avoid spreading the business certificate across many systems, we opt for creating an asymmetric key (JSON Web Key) and associate it to the newly created integration. In this example we use mkjwk.org.

  • Navigate to mkjwk.org in a browser

  • Fill in values like the example below and click Generate

    “New JWK”
    New JWK

    The output should look like this:

    “The JWK”
    The JWK

Now, the public part of the key should be added to the newly created integration in Samarbeidsportalen.

  • Navigate back to the integration in Samarbeidsportalen

  • Choose Egne public nøkler

    “Own public keys”
    Own public keys

  • Add two empty square bracets to the empty text box as shown below

    “Add array”
    Add array

  • Navigate back to the JWK generator site

    “The JWK”
    The JWK

  • Copy the public key of the JWK (marked 1 in the picture) and paste this into the array in Samarbeidsportalen.

    “Add public key”
    Add public key

  • Choose Legg til

The registration and configuration in Samarbeidsportalen is now complete, and the integration is ready to generate Maskinporten tokens on request from any client that can provide the private and public parts of the JWK.

Important values for client configuration

From samarbeidsportalen:

  • Integrasjonens identifikator

    This will be used in your client configuration. In Altinn libraries, this value is referred to as the client identifikator

From the JWK generation tool:

  • Public and private key pair (marked 2 in the picture below) This is what your client will use when calling the Maskinporten integration.

    “The JWK”
    The JWK

In Altinn libraries this key pair is referenced as EncodedJwk and must be base64 encoded before it is included in application configuration or uploaded to a Key Vault.

Base64encode.org can be used for encoding.

Platform Access token

The access to a subset of endpoints in the API is limited to callers within the Altinn ecosystem. These APIs require additional authorization in the form of a Platform Access Token.

Please reference developer documentation for the client system on how to generate the token.

Private APIs

The API contains a set of private APIs that are only accessible within the Events-component. These are marked as Private API in the OpenAPI specification and require an access token in the request header.