Home Connect API Gateway

Home Connect API Gateway - Docker container providing a REST API adapter for BSH Home Connect devices (Bosch, Siemens, Neff, Gaggenau)

---

What is this?

• A lightweight HTTP proxy/gateway in front of the official BSH Home Connect API.
• Provides an easy way to use the API without dealing with OAuth yourself.
• Ideal for home‑automation platforms, scripts, and services that just want a simple REST surface.

Key features

• Handles OAuth 2.0 Device Authorization (init, polling) and token refresh for you.
• Proxies requests to the Home Connect API via unified, minimal endpoints.
• Ships as a single Docker container; no external state required.
• Comes with an embedded OpenAPI UI at / for quick exploration.

---

Quick start (Docker)

• Prerequisite: Home Connect client ID.
• Start container:
  • Linux/macOS:
    • docker run -p 8080:8080 -e HOME_CONNECT_CLIENT_ID=YOUR_CLIENT_ID --name home-connect-gw larmic/home-connect-api-gateway:latest
  • Windows PowerShell:
    • docker run -p 8080:8080 -e HOME_CONNECT_CLIENT_ID=$Env:HOME_CONNECT_CLIENT_ID --name home-connect-gw larmic/home-connect-api-gateway:latest
• Open OpenAPI UI: http://localhost:8080 (serves docs).
• Automatic OAuth device flow on startup:
  • On start, the app calls the Home Connect Device Authorization endpoint and prints the verification URL and user code.
  • After an initial delay it will poll for the access token periodically until successful.
  • You can still trigger the steps manually via the HTTP endpoints below if desired.
• Manual OAuth endpoints (optional):
  1. POST http://localhost:8080/oauth/init → get user_code and verification_uri.
  2. Open the verification URL and enter the code.
  3. Poll tokens: POST http://localhost:8080/oauth/token until success (no authorization_pending).
  4. Optional refresh: POST http://localhost:8080/oauth/token/refresh.
• Check readiness: GET http://localhost:8080/health/ready (should report READY/UP).
• Use proxy:
  • Example: GET http://localhost:8080/proxy/api/homeappliances
  • Send your body with POST/PUT via the /proxy/... endpoint.

Configuration

• Required environment variables:
  • HOME_CONNECT_CLIENT_ID — your Home Connect client ID (mandatory)
• Optional environment variables (seconds):
  • DEVICE_FLOW_INITIAL_POLL_DELAY_SECONDS — delay before the first token poll; default 10s if not set. Docker image default: 10s.
  • DEVICE_FLOW_POLL_INTERVAL_SECONDS — interval between subsequent polls; default 5s if not set. Docker image default: 5s.

Notes

• The service requires HOME_CONNECT_CLIENT_ID at startup.
• Example HTTP requests are in misc/http/ (see home-connect-api.http and gateway-local.http).