v1.1.0 - Auth fix, API-key hardening & new features

Full changelog: v1.0.2...v1.1.0

Important

Two components, both bumped to 1.1.0 - the integration (HACS) and the Microsoft Family Safety Auth add-on. Update both. On HA OS/Supervised, leave the add-on API key blank to auto-generate one in /share/familysafety/.api_key; the integration picks it up automatically.

✨ New

• Connection-state sensor (#23) - a sensor.microsoft_family_safety_connection (🔌) exposing connected / degraded / disconnected plus mobile / web / cookie status, so you can see at a glance whether the auth session is healthy.

• Screen-time-limits switch (#24) - a per-child switch.<child>_screen_time_limits mirroring the Family Safety app: ON = limits enforced, OFF = unlimited time. Saves and restores the schedule so toggling never destroys it.

• Standalone Docker support (#25) - the auth service can now run as a standalone Docker container for HA Core / Container installs (no Supervisor), via Dockerfile.standalone, docker-compose.yml and a migration guide. A new auth URL option points the integration at the external container.

🔐 Security

• API key required on cookie & screen-time endpoints - closes a LAN exposure where GET /api/cookies returned the parent's Microsoft session cookies (full account takeover) and the screen-time endpoints accepted limit changes, both with no authentication. The add-on now always resolves a key (env > persisted /share/familysafety/.api_key > freshly generated), compares it in constant time, and the integration sends it automatically. The query-string key path and empty-key bypass are removed.

🐛 Fixed

• ClientSession auth crash (#22) - TypeError: 'ClientSession' object is not callable when another component (e.g. Family Link) replaced the aiohttp.ClientSession symbol. A compat shim now reuses Home Assistant's shared session and decodes JSON defensively, so Microsoft HTML error pages no longer crash the refresh (also fixes the recurring 400 in #23).

• approve_request granted ~1/10th of the requested time (#20) - the allowance is now pre-multiplied, so approving 60 min actually grants 60 min.

• Unstable lock / "schedule data disappeared" (#23) - lock_account no longer zeroes the schedule when the current policy is unreadable and nothing was previously saved, preventing irrecoverable loss of the child's schedule.

• Re-authentication redirect - stale cookies and the Chromium profile are wiped before a new auth session, so Microsoft no longer redirects to an expired session before login completes.

• Allowed-interval end time - interval conversion now ceils the end time, so 23:59 covers the 23:30-24:00 slot instead of drifting back to 23:30.

🚀 Performance

• Shared warm browser context - reused across fetch/post calls and closed after 180s idle, so bursts (a multi-child refresh, the 14 POSTs of a lock/unlock) skip the Chromium launch + navigation entirely, with automatic recycle-and-retry on auth-like errors.

• Cached web API session - the web client reuses one aiohttp session instead of creating one per request; dropped the raw_policy / raw_keys debug attributes that bloated the recorder.

🧹 Cleanup

• Unified the duplicated fetch/post and persistent-context paths into one _browser_call; FastAPI lifespan replaces the deprecated on_event hooks.
• A service-registration table replaces 17 copy-pasted handlers; a single FamilySafetyRequestButton class handles approve/deny; day-of-week lists centralized in const.py. datetime.utcnow() replaced with timezone-aware equivalents; removed dead code and unused config fields.

v1.1.0-rc1 v- Auth crash fix + screen time controls

⚠️ Release candidate. Please test and report any issue before the final v1.1.0.
After updating, restart Home Assistant (a reload is not enough) so the new entities are created.

Diagnosed and verified live on Home Assistant core-2026.5.1 / Python 3.14.2.

🐛 Bug fixes

TypeError: 'ClientSession' object is not callable (#22)

The pinned pyfamilysafety 1.1.2 created a new aiohttp.ClientSession() on every auth/refresh request. The integration now
patches the authenticator to reuse Home Assistant's shared aiohttp session, removing the crash (which also affected the Family
Link component) and the cascading 400/401 errors. Auth responses are now decoded defensively, so Microsoft HTML error pages no
longer crash the refresh cycle.

approve_request granted ~1/10th of the requested time (#20)

pyfamilysafety converted the extension with × 100 instead of × 1000 (seconds→ms), so 60 min granted only ~6 min. The
integration now compensates, and the requested duration is honored.

Unstable lock / "schedule data disappeared" (#23)

Locking an account could wipe the child's schedule when the current policy was unreadable and no backup existed. Locking now
refuses to zero an unreadable schedule with no restore point, preventing data loss.

✨ New features

• Connection state sensor (#23) — sensor.microsoft_family_safety_connection reports connected / degraded / disconnected
  with mobile API, web session and cookie diagnostics.
• Screen time limits switch (#24) — a per-account switch mirroring the Family Safety app: ON = limits enforced, OFF =
  unlimited time. The schedule is saved and restored, so toggling never destroys it.

---

Full changelog: v1.0.2...v1.1.0-rc1

v1.0.2 - Fix: OAuth redirect URL decoding

Fix: OAuth redirect URL decoding
Microsoft's OAuth callback URL often contains URL-encoded characters (e.g. %24 instead of $). The integration now automatically decodes the redirect URL before authentication, fixing "HTTP Unauthorized" errors that many users experienced when pasting the callback URL. (#18)

v1.0.1 - Full screen time control via browser automation

Highlights

Dual-component architecture

This release introduces a companion add-on (familysafety-playwright) that runs a headless Chromium browser to handle Microsoft web API authentication. The integration and addon work together - the addon maintains an authenticated browser session, and the integration routes API calls through it.

Why? Microsoft Family Safety has two APIs with different auth methods. The mobile API (OAuth token) handles basic reads, but screen time schedule modifications only work through the web API, which requires browser cookies and a CSRF token extracted from the page DOM. The addon solves this transparently.

Account Lock - the headline feature

The original per-platform lock (Windows/Xbox/Mobile) relied on a Microsoft API that no longer works. This release introduces a new Account Lock that actually works by manipulating screen time quotas:

• switch.<name>_lock - a single toggle per child
• ON = all 7-day quotas set to 0, all time intervals blocked
• OFF = previously saved quotas restored automatically
• Persists across HA restarts (saved via HA native .storage/)
• Optimistic updates - UI reflects the change immediately
• Works with automations, watchdogs, schedules

Screen time control from the UI

Daily limits and allowed time windows are fully adjustable from the dashboard:

• Number entities (number.<name>_monday_limit ... sunday_limit) - set daily allowance in minutes
• Time entities (time.<name>_monday_start/end ... sunday_start/end) - set allowed screen time window
• Optimistic updates - values reflect instantly, revert on failure
• All writes routed through the addon browser session (web API POST /family/api//st/day-allow)

17 services

Full control over Microsoft Family Safety from HA services:

Category	Services
Account Lock	lock_account, unlock_account
App Management	block_app, unblock_app, set_app_time_limit, remove_app_time_limit
Screen Time	set_screentime_limit, set_screentime_intervals
Web Filtering	block_website, remove_website, toggle_web_filter
Content & Purchases	set_age_rating, set_acquisition_policy
Requests	approve_request, deny_request
Platform (deprecated)	lock_platform, unlock_platform

Entity coverage

Type	Entities
Sensors	Screen Time, Account Info, Applications, Balance, Pending Requests, Web Filter, Screen Time Policy + per-device sensors
Switches	Account Lock (optimistic), App Block (per app), Platform Lock (deprecated)
Numbers	Daily screen time limit x7 days (optimistic)
Time	Interval start/end x7 days (optimistic)
Buttons	Approve / Deny pending requests

What changed since v0.6.0

New features

• Companion add-on (familysafety-playwright) with headless Chromium for web API authentication
• Account Lock switch with save/restore of screen time policies
• Screen time reads via addon browser session (cookie + CSRF based)
• Screen time writes via addon browser POST (/family/api//st/day-allow, /family/api//st/day-allow-int)
• Number entities for daily screen time limits (adjustable from UI)
• Time entities for screen time interval windows (start/end per day)
• Optimistic updates on lock switch, number entities, and time entities
• Dynamic addon hostname resolution via Supervisor API (portable across installations)
• Hub architecture with HA devices per child account and per physical device
• Configurable polling interval (30s-3600s) via options flow
• Full French translations for all config, options, and services

Reliability improvements

• Browser session management - cookies injected before navigation, OAuth silent flow handled automatically
• CSRF token extracted from DOM hidden input (not cookie) - matches what Microsoft expects
• Correct API headers (X-AMC-JsonMode, X-Requested-With: XMLHttpRequest)
• Lock/unlock uses best-effort recovery per day (no more silent partial failures)
• BaseException catch in browser context methods guarantees cleanup on CancelledError
• HTTP response bodies drained on error to prevent file descriptor leaks
• web_api reset on auth failure for proper reinitialization
• Number/Time entities raise HomeAssistantError with clear messages on failure
• Transient API errors during setup now retry instead of blocking the integration

Deprecations

• lock_platform / unlock_platform services and per-platform lock switches are deprecated (Microsoft broke the underlying API). Use Account Lock instead.

Automation example

# Lock at 21:00 on school nights, unlock at 07:00
automation:
  - alias: "Lock account at night"
    trigger:
      - platform: time
        at: "21:00:00"
    condition:
      - condition: time
        weekday: [sun, mon, tue, wed, thu]
    action:
      - action: switch.turn_on
        target:
          entity_id: switch.maceo_lock

  - alias: "Unlock account in the morning"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - action: switch.turn_off
        target:
          entity_id: switch.maceo_lock

Requirements

• Home Assistant 2024.1.0 or newer
• Home Assistant OS or Supervised (for the companion add-on)
• pyfamilysafety==1.1.2

Known limitations

• Unofficial API - Microsoft may change or break endpoints at any time
• Addon required - Screen time reads and writes need the companion addon with its browser session
• Account Lock is account-wide - locks all platforms simultaneously (no per-platform granularity via web API)
• Lock speed - 14 sequential API calls via browser (~10-20 seconds)
• One request at a time - the addon uses a single browser instance with a lock; concurrent requests are queued
• Session maintenance - Microsoft sessions can expire; occasional re-authentication via noVNC may be needed
• If HA storage is cleared while locked, unlock restores safe defaults (2h/day, 07:00-22:00)

v0.6.1-rc1 - Release Candidate

🐛 Bug Fixes

• Fix screen time duration attributes: formatted_time, hours, minutes, seconds were incorrect (minutes treated as seconds).
  Fixed for both Account Screen Time and Device Screen Time sensors.

✨ New Features

• New sensor: sensor.<device>_blocked
  State: blocked or active
  Dynamic icon: 🔒 locked / 🔓 unlocked
  Enables automations based on device lock status.

🧩 Debug (temporary)

• Added debug logging to test /v4/devicelimits/schedules/ endpoint.
• Investigating screen time limit availability.
• Search for DEBUG SCHEDULES: in Home Assistant logs.

v0.5.2

Merge pull request #2 from noiwid/claude/v0.5.1-test-011CUw4tYiQRf2A9…

v0.6.0 - Read-Only Integration (Control Features Non-Functional)

⚠️ Important Notice - Read-Only Integration

This release provides monitoring capabilities only. Device control features have been removed.

What Works ✅

• Screen time monitoring - Track daily usage and averages for each child account
• Device tracking - Monitor all registered devices and their usage
• Account information - Access profile data, balance, and application lists
• Family Link-style attributes - Detailed time formatting (hours, minutes, seconds, formatted_time)

What Doesn't Work ❌

Remote device control (blocking/unblocking) is not functional and has been removed from this release.

While the Microsoft Family Safety API accepts control commands (HTTP 201), devices do not actually block or
unblock. This appears to be a limitation on Microsoft's side, as even their official mobile app's "Lock device"
button no longer works reliably.

Why This Limitation?

This integration relies on an unofficial, undocumented API discovered through reverse engineering. Microsoft
provides no public API for Family Safety, and the control endpoints appear to be disabled or non-functional.

The original ha-familysafety integration by pantherale0 was
archived in October 2025, likely facing the same limitations.

What's New in v0.6.0

• Code refactoring - Improved maintainability with base classes and helper functions
• Bug fix - Screen time values now correctly display in seconds (was showing milliseconds)
• Enhanced attributes - Added formatted_time, hours, minutes, seconds to all screen time sensors
• Better documentation - Clear explanation of what works and what doesn't
• Cleaner codebase - Removed non-functional control features (switches, number entities, services)

For Contributors 🤝

We're actively seeking help to:

• Reverse engineer working device control endpoints through network traffic analysis
• Document the complete Microsoft Family Safety API
• Improve authentication (automatic token refresh, OAuth2 support)

See CONTRIBUTING.md for details.

EXPERIMENTAL - Platform Blocking Fix

This release fixes critical bugs in the platform blocking functionality. Testing required to verify if it actually works with Microsoft's API.

🐛 Bug Fixes

• Fixed incorrect API parameter types for override_device()
• Now uses proper OverrideTarget enum (WINDOWS/MOBILE/XBOX)
• Now uses proper OverrideType enum (UNTIL/CANCEL)
• Properly converts duration to datetime for valid_until

🔄 Breaking Changes

Switch entities changed from per-device to per-platform:

• Before: switch.desktop_9n6pnll
• Now: switch.maceo_windows

Services updated:

• Now require account_id + platform instead of device_id
• Platform options: windows, mobile, xbox

🧪 How to Test

1. Install v0.5.1
2. Delete and recreate the integration
3. You'll see platform switches (e.g., "Macéo Windows")
4. Try toggling the switch OFF for 5 minutes
5. Check if the device actually blocks

⚠️ Important Notes

• If blocking doesn't work, fall back to v0.6.0 (monitoring only)
• API confirmed by pyfamilysafety developer as correct
• Microsoft's API may still not work despite correct parameters

Install: Installation Guide

Microsoft Family Safety v0.5.0 - Initial Release

🎉 Microsoft Family Safety v0.5.0 - Initial Release

First public release of the Microsoft Family Safety integration for Home Assistant!

🌟 Features

📊 Account Monitoring

• Daily screen time tracking - Monitor daily usage for each child account
• Average screen time statistics - Analyze usage trends over multiple days
• Account balance - Track account balance when enabled in Family Safety
• Profile information - Display first name, surname, and profile picture
• Application tracking - Count and list all installed applications per account

📱 Device Management

• Screen time per device - Detailed tracking for each registered device
• Device information - Model, operating system, last seen timestamp
• Remote lock/unlock - Control device access via switches
• Real-time status - Monitor block status and device availability
• Multiple device support - Manage all devices registered in Family Safety

🎯 Entities Created

Sensors (per child account):

• sensor.<name>_screen_time - Daily screen time in minutes
• sensor.<name>_account_info - Account details with profile picture
• sensor.<name>_applications - Application count and complete list
• sensor.<name>_balance - Account balance (if applicable)

Sensors (per device):

• sensor.<device>_screen_time - Device-specific screen time
• sensor.<device>_info - Detailed device information

Switches (per device):

• switch.<device> - Device control (ON = unblocked, OFF = blocked)

⚙️ Services

• microsoft_family_safety.block_device - Block a device (with optional duration)
• microsoft_family_safety.unblock_device - Unblock a previously blocked device
• microsoft_family_safety.approve_request - Approve screen time extension requests
• microsoft_family_safety.deny_request - Deny screen time extension requests

🔐 Authentication

• Secure OAuth 2.0 authentication flow with Microsoft
• Refresh token storage for automatic re-authentication
• Step-by-step authentication guide in documentation
• Support for re-authentication when tokens expire

📦 Installation

HACS (Recommended)

1. Add custom repository: https://github.com/noiwid/HAFamilySafety
2. Search for "Microsoft Family Safety"
3. Download and install
4. Restart Home Assistant

Manual Installation

1. Download and extract the latest release
2. Copy custom_components/microsoft_family_safety to your Home Assistant config
3. Restart Home Assistant

See INSTALL.md for detailed instructions.

📖 Documentation

• README.md - Complete integration documentation with automation examples
• INSTALL.md - Step-by-step installation and configuration guide
• French and English translations - Full UI support for both languages

🔧 Technical Details

• Home Assistant Core >= 2024.1.0 (recommended)
• pyfamilysafety 1.1.2 (pinned for stability)
• Cloud polling - 5-minute update interval (configurable)
• Integration type - Hub (manages multiple devices/accounts)

🤝 Automation Examples

The integration supports powerful automations:

• Automatic bedtime device locking
• School day morning unlocks
• Screen time limit alerts
• Daily usage reports
• Conditional access based on homework completion

See the README for complete automation examples.

⚖️ Important Notice

This integration uses unofficial APIs from Microsoft Family Safety. It is not affiliated with, endorsed, or sponsored by Microsoft Corporation.

• Microsoft may modify or restrict API access at any time
• Use at your own risk
• Comply with Microsoft's terms of service

🙏 Credits

• @pantherale0 - pyfamilysafety library
• Inspired by HAFamilyLink

📝 Full Changelog

Initial release with complete Microsoft Family Safety integration support.

---

Install now: HACS Installation Guide

Need help? Create an issue