aiounifiaccess

Async Python client for the UniFi Access API.

• Full REST API coverage — all endpoints from API v4.0.10
• Real-time events — WebSocket listener with auto-reconnect and typed event models
• Webhook receiver — built-in HTTP server for webhook events with signature verification
• Idempotent webhook registration — ensure_endpoint() and setup_webhook() handle subscription management
• Pydantic v2 models — fully typed request/response objects
• Async-native — built on aiohttp for composability with other async libraries

Installation

pip install aiounifiaccess

Quick Start

import asyncio
import os
from aiounifiaccess import UniFiAccessClient

async def main():
    async with UniFiAccessClient(
        host=os.environ["UNIFI_ACCESS_HOST"],
        api_token=os.environ["UNIFI_ACCESS_TOKEN"],
    ) as client:
        # List all users
        users, pagination = await client.users.list()
        for user in users:
            print(f"{user.first_name} {user.last_name} ({user.status})")

        # Get a specific door
        door = await client.doors.get("door-id-here")
        print(f"{door.name}: {door.door_lock_relay_status}")

        # Remote unlock
        await client.doors.unlock("door-id-here", actor_name="API Script")

asyncio.run(main())

Real-Time Events

UniFi Access delivers events through two channels:

Notably, credential-based door unlock events (access.door.unlock) are webhook-only — they are not delivered over the WebSocket. To receive all event types, you need both channels.

The WebSocket also delivers undocumented status events not listed in the official API reference. These are typed and parsed by the library:

The DeviceUpdateEvent is particularly useful — its configs list contains key/value pairs for DPS states, lock relay states, and power readings. For example, detecting "door left open":

from aiounifiaccess import DeviceUpdateEvent

@client.on(DeviceUpdateEvent)
async def handle_device_update(event: DeviceUpdateEvent):
    for cfg in event.data.configs:
        if cfg.tag == "hub_action" and cfg.key.endswith("_dps"):
            port = cfg.key.replace("input_", "").replace("_dps", "")
            state = "open" if cfg.value == "on" else "closed"
            print(f"Port {port} DPS: {state}")

WebSocket Only

If you only need doorbell and remote unlock events:

import asyncio
import os
from aiounifiaccess import UniFiAccessClient, RemoteViewEvent

async def main():
    async with UniFiAccessClient(
        host=os.environ["UNIFI_ACCESS_HOST"],
        api_token=os.environ["UNIFI_ACCESS_TOKEN"],
    ) as client:

        @client.on(RemoteViewEvent)
        async def handle_doorbell(event: RemoteViewEvent):
            print(f"Doorbell ring at {event.data.door_name}")

        await client.listen()

asyncio.run(main())

WebSocket + Webhook (Recommended)

To receive all events including credential-based door unlocks, use setup_webhook(). This registers a webhook subscription on the UniFi controller, starts a local HTTP receiver, and runs both channels concurrently:

import asyncio
import os
from aiounifiaccess import (
    UniFiAccessClient,
    DoorUnlockEvent,
    DoorPositionEvent,
    RemoteViewEvent,
)

async def main():
    async with UniFiAccessClient(
        host=os.environ["UNIFI_ACCESS_HOST"],
        api_token=os.environ["UNIFI_ACCESS_TOKEN"],
    ) as client:

        # Register webhook on the controller and start local receiver.
        # The controller will POST events to this URL.
        await client.setup_webhook("https://myserver:8080/webhook")

        @client.on(DoorUnlockEvent)
        async def handle_unlock(event: DoorUnlockEvent):
            actor = event.data.actor.name
            door = event.data.location.name
            method = event.data.object.authentication_type
            print(f"{actor} unlocked {door} via {method}")

        @client.on(DoorPositionEvent)
        async def handle_dps(event: DoorPositionEvent):
            print(f"{event.data.location.name}: {event.data.object.status}")

        @client.on(RemoteViewEvent)
        async def handle_doorbell(event: RemoteViewEvent):
            print(f"Doorbell ring at {event.data.door_name}")

        # Runs both WebSocket and webhook receiver until stopped
        await client.listen()

asyncio.run(main())

setup_webhook() is idempotent — if a webhook subscription already exists for the same URL and event set, it reuses it. If the URL matches but the events differ, it updates the existing subscription. By default it subscribes to all known webhook event types.

Subscribing to Specific Events

Use WebhookEventType to subscribe to only the events you need:

from aiounifiaccess import WebhookEventType

await client.setup_webhook(
    "https://myserver:8080/webhook",
    events=[
        WebhookEventType.DOOR_UNLOCK,
        WebhookEventType.DEVICE_DPS_STATUS,
    ],
)

Available event types:

Manual Webhook Configuration

If you prefer to manage webhook registration separately (or already have one registered), pass the secret directly:

async with UniFiAccessClient(
    host=os.environ["UNIFI_ACCESS_HOST"],
    api_token=os.environ["UNIFI_ACCESS_TOKEN"],
    webhook_secret="your_webhook_secret",
    webhook_port=8080,
) as client:
    # ...handlers...
    await client.listen()

Or use the webhook manager API directly:

# Idempotent registration (create or reuse)
endpoint = await client.webhooks.ensure_endpoint(
    "https://myserver:8080/webhook",
    "my-app",
)
print(f"Secret: {endpoint.secret}")

# Or manual CRUD
endpoints = await client.webhooks.list_endpoints()
await client.webhooks.delete_endpoint(endpoint.id)

Standalone Webhook Receiver

The WebhookReceiver can be used independently of the full client:

import asyncio
from aiounifiaccess import WebhookReceiver, DoorUnlockEvent
from aiounifiaccess.events.handler import EventHandler

handler = EventHandler()

@handler.on(DoorUnlockEvent)
async def handle(event: DoorUnlockEvent):
    print(f"{event.data.actor.name} unlocked {event.data.location.name}")

async def main():
    receiver = WebhookReceiver("your_webhook_secret", port=8080)
    await receiver.listen(handler)

asyncio.run(main())

Webhook Signature Verification

For custom webhook handling outside the built-in receiver:

from aiounifiaccess import verify_webhook_signature

is_valid = verify_webhook_signature(
    secret="your_webhook_secret",
    signature_header=request.headers["Signature"],
    body=await request.read(),
)

Debug Logging

To see all raw incoming messages on either channel:

import logging

# Both channels
logging.getLogger("aiounifiaccess.events").setLevel(logging.DEBUG)

# Or individually
logging.getLogger("aiounifiaccess.events.listener").setLevel(logging.DEBUG)   # WebSocket
logging.getLogger("aiounifiaccess.events.receiver").setLevel(logging.DEBUG)   # Webhook

API Managers

Compatibility

Requirements

• Python 3.11+
• aiohttp >= 3.9
• pydantic >= 2.0

License

MIT