Altinn Notifications API
An overview of the Altinn Notifications API
The Altinn Notifications API is an HTTP-based RESTful API that provides endpoints and actions for ordering, managing and reviewing notifications sent through Altinn.
Base URL
The following base urls correspond to each environment
AT (Private Altinn acceptance test environment)
https://platform.{environment}.altinn.cloud/notifications/api/v1TT02 (Application owner test environment)
https://platform.tt02.altinn.cloud/notifications/api/v1Production
https://platform.altinn.cloud/notifications/api/v1
Authentication & Authorization
Altinn token
The Notifications 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 Notifications 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 Notifications 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.
Prerequisites
A user in Samarbeidsportalen with access to Selvbetjening.
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 Choose Ny integrasjon
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 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 The output should look like this:
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 Add two empty square bracets to the empty text box as shown below
Add array Navigate back to the JWK generator site
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 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
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.