Municipality setup

Before a vendor can call Open Aidn APIs for a municipality, the integration must be enabled for that municipality and an OAuth client must be configured with the agreed scopes.

This setup is performed by municipality administrators or Aidn administrators in the admin portal.

Setup overview

flowchart TD
    A[Open the municipality in the admin portal] --> B[Open the integration overview]
    B --> C[Enable or start the integration]
    C --> D[Create a client for the vendor]
    D --> E[Select approved scopes]
    E --> F[Register the vendor public key]
    F --> G[Share client ID and required configuration values]

Integration state

The integration must be enabled for the municipality before a client can be created for it. An integration that is active or in progress can have OAuth clients connected to it.

Client setup

When creating a client, the administrator should:

• Use a clear client name that identifies the vendor, use case, and environment.
• Select only the scopes required for the approved use case.
• Register at least one public key for the client, or generate a key pair in the admin portal.
• Record the generated client ID and key ID (kid) so the vendor can request tokens.
• If the vendor supplies its own key, register only the public key. The vendor should keep the private key.
• If the admin portal generates the key pair, transfer the private key securely to the vendor. The private key is shown only once and cannot be retrieved later.

Use-case configuration and testing

Most integrations need use-case-specific configuration in both Aidn and the third-party system. The exact values and setup steps depend on the approved use case.

The municipality should confirm:

• The required use-case-specific configuration has been identified.
• The configuration has been completed in Aidn.
• The corresponding configuration has been completed in the third-party system.
• The integration has been tested with representative data and expected workflows.
• The municipality, vendor, and Aidn agree that the setup is ready for production rollout.

Aidn will normally assist with test environment setup and technical onboarding. This is not usually something the municipality performs alone.

Operational responsibilities

The municipality and vendor should agree how to handle:

• Key rotation and credential changes.
• Changes to use-case-specific configuration.
• Monitoring and troubleshooting of failed API calls.
• Contact points for incidents or suspected credential compromise.