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.

Municipal or Aidn administrators complete this setup 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 you can create a client for it. OAuth clients can be connected to integrations that are active or still starting up.

Client setup

When creating a client, the administrator should:

• Use a clear client name that identifies the vendor and use case.
• 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 can’t be retrieved later.

Use-case configuration and testing

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

The municipality should confirm:

• The required configuration for the use case 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 normally helps set up the test environment and provides technical onboarding. The municipality isn’t expected to do this 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.