unifi-api

UniFi API Guidelines

Authentication with API Keys

This project uses the official UniFi Cloud API with API key authentication.

Authentication Method:

• Use UNIFI_API_KEY environment variable for authentication
• API key is passed via the X-API-Key HTTP header
• No session management or cookies required (stateless authentication)

NEVER hardcode API keys:

# ❌ BAD - Hardcoded API key
headers = {
    "X-API-Key": "abc123def456..."
}

# ✅ GOOD - Load from environment
from src.config.config import Settings

settings = Settings()
headers = {
    "X-API-Key": settings.api_key
}

API Access Modes

Support both cloud and local gateway access modes:

Cloud API (Default):

# Base URL: https://api.ui.com/v1/
settings.api_type = "cloud"
settings.cloud_api_url = "https://api.ui.com"

Local Gateway Proxy:

# Base URL: https://{gateway-ip}/proxy/network/integration/v1/
settings.api_type = "local"
settings.local_host = "192.168.2.1"
settings.local_port = 443

Read-Only Limitation

IMPORTANT: The Early Access API is currently read-only.

# ✅ ALLOWED - Read operations
async def list_devices(site_id: str):
    """List all devices - read operation."""
    devices = await client.get(f"/v1/sites/{site_id}/devices")
    return devices

# ❌ NOT AVAILABLE - Write operations (will fail)
async def create_network(name: str, vlan_id: int):
    """Create network - not yet supported in EA API."""
    # This will return 403 Forbidden in current API version
    raise NotImplementedError(
        "Write operations are not available in the Early Access API. "
        "This feature will be available in v1 Stable release."
    )

Handling write requests:

• Document that write operations are not yet available
• Return clear error messages to users
• Consider implementing a "preview" mode that shows what would be created
• Monitor UniFi API release notes for v1 Stable availability

Rate Limiting Considerations