OAuth2 Authentication Overview

This section covers setting up OAuth2 authentication to access the HouMeerOver API securely. OAuth2 provides secure, token-based access to your municipality's data.

What is OAuth2?

OAuth2 is an industry-standard authorization framework that enables secure API access without sharing passwords. The HouMeerOver API uses OAuth2 with the following characteristics:

• Municipality-scoped: Applications can only access data from their municipality
• Token-based: Uses bearer tokens for request authentication
• Scope-controlled: Different scopes provide access to different functionality
• Secure: Industry-standard implementation with proper encryption

How OAuth2 Works with HouMeerOver

Authentication Flow

1. Create Application: Set up an OAuth2 application in HouMeerOver admin
2. Get Credentials: Receive Client ID and Client Secret
3. Request Token: Exchange credentials for access token
4. Make API Calls: Use token in Authorization header
5. Token Refresh: Get new tokens when they expire

Supported Authorization Grant Types

HouMeerOver supports multiple OAuth2 authorization grant types to accommodate different integration scenarios:

Grant Type	Use Case	OIDC Support	Recommended For
Client Credentials	Server-to-server integration	No	Municipal system integrations, automated processes
Authorization Code	Interactive applications	Yes (optional)	Web applications, mobile apps with user login
Implicit	Client-side applications	Yes (optional)	Single-page applications, JavaScript apps
OpenID Connect Hybrid	Complex identity scenarios	Yes	Applications requiring both authentication and authorization

Available Scopes

The system currently supports these OAuth2 scopes:

Scope	Description	Access Level
calculations:read	Read access to calculation data	View calculation results and details
oidc	OpenID Connect functionality	Basic user identification

Note: Additional scopes may be available - check the OpenAPI documentation for the complete current list.

Use Cases

Server-to-Server Integration

Most municipal integrations use Client Credentials flow:

• Direct API access from municipal systems
• Automated data synchronization
• Background processing applications
• System-to-system integration

Interactive Applications

For applications with user interaction, Authorization Code flow is available:

• Web applications with user login
• Mobile applications
• Third-party integrations requiring user consent

Security Features

Municipality Scoping

• Each OAuth2 application is automatically scoped to its municipality
• Cannot access data from other municipalities
• Provides natural data isolation and security

Token Security

• Limited lifetime tokens (typically 1 hour)
• Secure token storage requirements
• Industry-standard encryption and signing

Optional IP-based access restrictions

• Only allow API access to select IP addresses
• Optionally configurable for each application, regardless of flow
• Whitelist specific IP addresses or entire network ranges (with CIDR notation)

API Reference

For complete endpoint documentation and interactive testing, visit the HouMeerOver API Documentation.

Getting Started

Choose the appropriate authentication approach based on your integration needs:

Server-to-Server Integration

Server-to-Server Authentication

Best for municipal system integrations and automated processes:

• Direct API access from municipal systems
• Automated data synchronization
• Background processing applications
• No user interaction required

Delegated User Access

Delegated User Authentication

Best for applications requiring user consent and interaction:

• Web applications with user login
• Mobile applications
• Third-party integrations requiring user authorization
• Enhanced security and user control

Implementation Guide

1. Choose your flow based on your use case above
2. Follow the specific guide for detailed implementation steps
3. Test your integration with the HouMeerOver API
4. Implement security best practices from the respective guides

---

Ready to begin? Choose Server-to-Server Authentication for municipal system integration or Delegated User Authentication for user-interactive applications.