Kwikset Smart Locks for Home Assistant

A custom Home Assistant integration for Kwikset Smart Locks using the unofficial Kwikset cloud API. Control and monitor your Kwikset smart locks directly from Home Assistant.

🚨 Breaking Change Notice (v0.4.0)

⚠️ IMPORTANT: If you are upgrading from v0.3.x to v0.4.0, manual steps are required!

The integration folder has been renamed from kwikset-ha to kwikset to follow Home Assistant's domain naming conventions. HACS cannot automatically upgrade due to this change.

📖 Read the Migration Guide before upgrading!

Quick Summary:

Remove the integration from Settings → Devices & Services

Uninstall via HACS

Delete the old folder: custom_components/kwikset-ha

Restart Home Assistant

Re-add the repository in HACS and download v0.4.0

Restart Home Assistant and re-configure the integration

Your automations and entity IDs will continue to work after migration.

✨ Features

Lock Control

Lock/Unlock: Control your Kwikset smart locks remotely
Real-time Status: View lock state (locked/unlocked) with automatic polling
Battery Monitoring: Track battery percentage with low battery alerts

Device Settings

LED Indicator: Toggle the LED status light on/off
Audio Feedback: Enable/disable keypad sounds
Secure Screen: Control the secure screen display mode

Smart Features

Multi-Home Support: Configure multiple Kwikset homes in a single HA instance
Dynamic Device Discovery: New locks are automatically detected every 5 minutes
Stale Device Removal: Devices removed from your account are automatically cleaned up
MFA Support: Full multi-factor authentication support (SMS and authenticator apps)
Proactive Token Refresh: Authentication tokens are refreshed before expiry

Connection Modes

Mode	Description	Polling Interval
Cloud Polling	Connects via Kwikset cloud API	15-60 seconds (configurable)

Note: This integration uses cloud polling only. Local/Bluetooth control is not supported as Kwikset does not provide a local API.

🔐 Supported Devices

This integration supports Kwikset smart locks that are compatible with the Kwikset app:

Product Line	Models	Features
Halo Series	Halo, Halo Touch	WiFi, Fingerprint (Touch)
Aura Series	Aura	Bluetooth + WiFi Bridge
Obsidian	Obsidian	Bluetooth + WiFi Bridge
Premis	Premis	HomeKit, Bluetooth
SmartCode	916, 914, 913	Z-Wave/Zigbee (via Kwikset app)

Compatibility: Any lock that can be controlled via the Kwikset iOS/Android app should work with this integration.

Verified Working Models

Kwikset Halo Touch (WiFi + Fingerprint)
Kwikset Halo (WiFi)
Kwikset Aura (Bluetooth + WiFi Bridge)

📡 Data Updates

This integration uses cloud polling to fetch device status from the Kwikset cloud API.

Polling Behavior

Aspect	Details
Default Interval	30 seconds
Configurable Range	15-60 seconds
Update Method	Cloud polling via Kwikset API
Device Discovery	Every 5 minutes (automatic)

How It Works

State Polling: The integration polls the Kwikset cloud API at your configured interval (default: 30 seconds) to fetch the current lock state, battery level, and settings.
Command Execution: When you lock/unlock via Home Assistant, the command is sent to the Kwikset cloud, which then relays it to your lock over WiFi. The UI immediately shows "Locking" or "Unlocking" state for instant feedback.
Device Discovery: Every 5 minutes, the integration checks for new or removed devices and updates automatically.
Token Refresh: Authentication tokens are automatically refreshed before expiry (5 minutes buffer) to prevent authentication failures.

Optimistic State Updates

When you issue a lock or unlock command, the integration uses optimistic state updates to provide immediate feedback:

Instant Feedback: The lock shows "Locking" or "Unlocking" state immediately after you click the button
API Confirmation: The actual command is sent to the Kwikset cloud and executed on the lock
State Verification: The integration polls the API to confirm the final state
Timeout Protection: If the API doesn't respond within 30 seconds, the optimistic state resets

This provides a responsive user experience while maintaining accurate state representation.

Latency Considerations

State Updates: Lock state changes made locally (keypad, fingerprint, physical key) may take up to your polling interval to appear in Home Assistant.
Command Latency: Lock/unlock commands typically execute within 2-5 seconds, depending on your lock's WiFi connection.
No Push Updates: The Kwikset API does not support push notifications, so all updates rely on polling.

Tip: If you need faster status updates, reduce the polling interval to 15 seconds. This increases API requests but provides more responsive state updates.

⚠️ Known Limitations

This section describes known limitations of the integration (not bugs).

API Limitations

Limitation	Description
Cloud-Only	No local control available. All communication goes through Kwikset's cloud servers.
Unofficial API	This integration uses an undocumented API that Kwikset may change without notice.
No Push Updates	The API doesn't support real-time push notifications. All updates rely on polling.
Rate Limiting	Excessive API calls may be rate-limited by Kwikset. Keep polling interval ≥15 seconds.

Feature Limitations

Limitation	Description
No User Codes	Managing user access codes is not supported. Use the Kwikset app for this.
No Access Logs	Access history/event logs are not available through the API.
No Scheduling	Built-in lock schedules cannot be managed. Use Home Assistant automations instead.
No Bluetooth	Direct Bluetooth communication is not supported; WiFi bridge is required.
No HomeKit Sync	HomeKit-paired locks must still use cloud API; HomeKit state is not synced.

Device Limitations

Limitation	Description
WiFi Required	Locks must be connected to WiFi (directly or via bridge) for remote control.
Home Required	Locks must be assigned to a "Home" in the Kwikset app before they appear in this integration.
Single Account	Each Home Assistant instance should use one Kwikset account per home to avoid token conflicts.

Secure Screen Switch

The Secure Screen switch is disabled by default because:

It's a less commonly used feature
Reduces resource usage for users who don't need it
Can be enabled manually in entity settings if needed

To enable: Settings → Devices & Services → Kwikset → Select your lock → Entities → Enable "Secure Screen"

📌 Requirements

Prerequisites

Kwikset Account: A valid Kwikset account with your locks registered
Kwikset Home: You must create a "Home" in the Kwikset app and add your locks to it
Home Assistant: Version 2024.1.0 or newer recommended
HACS: For easy installation (optional but recommended)

Important Notes

⚠️ KWIKSET DOESN'T PROVIDE AN OFFICIALLY SUPPORTED API

This integration uses an unofficial API. Kwikset may change their API at any time, which could temporarily break this integration.

⚠️ HOME SETUP REQUIRED

This integration only works if you have created a Home in the Kwikset app or have been invited to a Home. Locks must be assigned to a Home.

📦 Installation

⚠️ Upgrading from v0.3.x? See the Migration Guide for required steps.

Option 1: HACS (Recommended)

Click the button above, or:
- Open HACS in Home Assistant
- Click "Integrations"
- Click the three dots menu → "Custom repositories"
- Add https://github.com/explosivo22/kwikset-ha as an Integration
Search for "Kwikset Smart Locks" and install
Restart Home Assistant
Continue to Configuration

Option 2: Manual Installation

Download the latest release from GitHub Releases

Extract and copy the kwikset folder to your custom_components directory:

config/
└── custom_components/
    └── kwikset/
        ├── __init__.py
        ├── config_flow.py
        ├── const.py
        └── ...

Restart Home Assistant
Continue to Configuration

⚠️ Manual Installation Warning: You won't receive automatic update notifications. Subscribe to repository releases for update alerts.

⚙️ Configuration

Initial Setup

Click the button above, or:
- Go to Settings → Devices & Services
- Click + Add Integration
- Search for "Kwikset Smart Locks"
Enter your Kwikset account credentials (email and password)
If MFA is enabled, enter the verification code
Select the Kwikset Home to configure
Done! Your locks will appear as devices

Installation Parameters

The following parameters are required during the integration setup:

Parameter	Required	Description
Email	Yes	The email address associated with your Kwikset account. This is the same email you use to log into the Kwikset mobile app.
Password	Yes	Your Kwikset account password. This is stored securely and used to authenticate with the Kwikset cloud API.
Verification Code	Conditional	A 6-digit code required if you have Multi-Factor Authentication (MFA) enabled on your Kwikset account. The code is sent via SMS or generated by your authenticator app, depending on your MFA configuration.
Home	Yes	Select which Kwikset home to configure. Each home is set up as a separate integration entry. Only homes that haven't been configured yet will be shown.

Note: Your credentials are used to authenticate with the Kwikset cloud API. Access and refresh tokens are stored locally and automatically renewed. Your password is only used during initial setup and reauthentication.

Configuration Options

After setup, you can configure the integration options by going to Settings → Devices & Services, finding the Kwikset integration, and clicking Configure.

Option	Description	Default	Range
Polling interval	How often to poll the Kwikset cloud for device status updates. Lower values provide faster status updates but increase API requests. Higher values reduce API load but status updates will be less frequent.	30 seconds	15-60 seconds

Tip: A 30-second polling interval is recommended for most users. Reduce to 15 seconds if you need faster feedback, or increase to 60 seconds if you rarely check lock status remotely.

Multiple Homes

To add additional Kwikset homes:

Go to Settings → Devices & Services
Click + Add Integration
Search for "Kwikset Smart Locks"
Enter credentials and select the next home

Each home creates a separate integration entry.

🗑️ Removal

Removing the Integration

To remove the Kwikset integration from Home Assistant:

Go to Settings → Devices & Services
Find the Kwikset Smart Locks integration
Click the three dots menu (⋮) on the integration card
Select Delete
Confirm the removal

This will remove all Kwikset devices and entities from Home Assistant. Your Kwikset account and locks are not affected.

Uninstalling via HACS

To completely uninstall the integration:

First, remove the integration (steps above)
Open HACS → Integrations
Find "Kwikset Smart Locks"
Click the three dots menu (⋮)
Select Remove → Remove
Restart Home Assistant

Manual Uninstallation

If you installed manually:

First, remove the integration from Settings (steps above)
Delete the custom_components/kwikset folder
Restart Home Assistant

🎛️ Entities

Each Kwikset lock creates the following entities:

Lock Entity

Entity	Type	Description
`lock.<device_name>_lock`	Lock	Lock/unlock control and state

Sensor Entities

Entity	Type	Category	Description
`sensor.<device_name>_battery`	Sensor	Diagnostic	Battery percentage (0-100%)

Switch Entities

Entity	Type	Category	Description
`switch.<device_name>_led`	Switch	Config	LED indicator on/off
`switch.<device_name>_audio`	Switch	Config	Audio feedback on/off
`switch.<device_name>_secure_screen`	Switch	Config	Secure screen mode on/off

Service Actions

This integration uses standard Home Assistant service actions:

Lock Actions

Action	Description	Example
`lock.lock`	Lock the door	`service: lock.lock` `target: entity_id: lock.front_door_lock`
`lock.unlock`	Unlock the door	`service: lock.unlock` `target: entity_id: lock.front_door_lock`

Switch Actions

Action	Description	Example
`switch.turn_on`	Enable a setting	`service: switch.turn_on` `target: entity_id: switch.front_door_led`
`switch.turn_off`	Disable a setting	`service: switch.turn_off` `target: entity_id: switch.front_door_led`
`switch.toggle`	Toggle a setting	`service: switch.toggle` `target: entity_id: switch.front_door_audio`

Note: This integration does not provide custom service actions. All functionality uses standard Home Assistant lock and switch services.

🏠 Use Cases & Automations

Example 1: Auto-Lock at Night

automation:
  - alias: "Auto-lock front door at night"
    trigger:
      - platform: time
        at: "22:00:00"
    condition:
      - condition: state
        entity_id: lock.front_door_lock
        state: "unlocked"
    action:
      - service: lock.lock
        target:
          entity_id: lock.front_door_lock
      - service: notify.mobile_app
        data:
          message: "Front door has been auto-locked for the night"

Example 2: Low Battery Alert

automation:
  - alias: "Kwikset low battery alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.front_door_battery
        below: 20
    action:
      - service: notify.mobile_app
        data:
          title: "🔋 Low Battery Alert"
          message: "Front door lock battery is at {{ states('sensor.front_door_battery') }}%"

Example 3: Welcome Home Unlock

automation:
  - alias: "Unlock when arriving home"
    trigger:
      - platform: zone
        entity_id: person.john
        zone: zone.home
        event: enter
    condition:
      - condition: state
        entity_id: lock.front_door_lock
        state: "locked"
      - condition: time
        after: "06:00:00"
        before: "23:00:00"
    action:
      - service: lock.unlock
        target:
          entity_id: lock.front_door_lock

Example 4: Lock Status Dashboard Card

type: entities
title: Front Door Lock
entities:
  - entity: lock.front_door_lock
  - entity: sensor.front_door_battery
  - entity: switch.front_door_led
  - entity: switch.front_door_audio

Example 5: Guest Access Notification

automation:
  - alias: "Notify when lock state changes"
    trigger:
      - platform: state
        entity_id: lock.front_door_lock
    action:
      - service: notify.mobile_app
        data:
          title: "🔐 Lock Status Changed"
          message: >
            Front door was {{ trigger.to_state.state }} at 
            {{ now().strftime('%I:%M %p') }}

🔧 Troubleshooting

Common Issues

"Cannot connect" error during setup

Cause: Network issue or Kwikset API unavailable

Solutions:

Check your internet connection
Verify Kwikset app works on your phone
Try again in a few minutes (API may be temporarily down)
Check Kwikset server status

"Invalid authentication" error

Cause: Incorrect credentials or expired session

Solutions:

Verify email and password are correct
Try logging into the Kwikset app to confirm credentials
Reset your Kwikset password if needed

MFA verification code not working

Cause: Code expired or incorrect MFA type

Solutions:

Ensure you're using the most recent code
Check the correct MFA method (SMS vs authenticator app)
Codes expire quickly - enter within 30 seconds

"No available homes" error

Cause: No homes configured in Kwikset account

Solutions:

Open the Kwikset app
Create a new Home
Add your locks to the Home
Retry the integration setup

Locks not appearing after setup

Cause: Locks not assigned to the selected home

Solutions:

Open the Kwikset app
Verify locks are in the selected home
Wait 5 minutes for dynamic discovery
Use the "Reconfigure" option to trigger discovery

Lock shows "unavailable"

Cause: Communication issue with Kwikset cloud

Solutions:

Check if the lock is online in the Kwikset app
Verify the lock has good WiFi signal
Check lock battery level
Restart the integration

Actions fail with "Failed to lock/unlock"

Cause: API error or lock offline

Solutions:

Try the action in the Kwikset app
Check lock battery level
Verify lock WiFi connection
Check Home Assistant logs for details

Debug Logging

Enable debug logging to troubleshoot issues:

# configuration.yaml
logger:
  default: info
  logs:
    custom_components.kwikset: debug
    aiokwikset: debug

Getting Help

Check the GitHub Issues for known problems
Review Home Assistant logs for error details
Use the Diagnostics feature: Settings → Devices & Services → Kwikset → Download Diagnostics
Open a new issue with diagnostics file attached (sensitive data is automatically redacted)

📊 Quality Scale Compliance

This integration meets the Home Assistant Integration Quality Scale Platinum tier.

Current Status: Platinum ✅

Tier	Status	Requirements Met
Bronze	✅ Complete	18/18
Silver	✅ Complete	10/10
Gold	✅ Complete	18/18
Platinum	✅ Complete	3/3

Key Quality Features

Config Flow: Full UI-based setup with MFA support
Reauthentication: Automatic token refresh with reauth flow
Dynamic Discovery: Automatic detection of new/removed devices
Stale Device Removal: Cleanup of devices removed from account
Diagnostics: Full diagnostic data with sensitive info redaction
Test Coverage: Comprehensive pytest test suite with 95%+ coverage
Type Safety: Full type annotations with py.typed marker
Strict Typing: All modules pass mypy strict type checking
Async Dependency: Uses fully async aiokwikset library
Inject WebSession: Passes Home Assistant's aiohttp session to API client
Error Handling: Proper exception handling with user-friendly messages

See INTEGRATION_QUALITY_SCALE.md for detailed compliance tracking.

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pytest tests/)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/explosivo22/kwikset-ha.git
cd kwikset-ha

# Install dependencies
pip install -r requirements_test.txt

# Run tests
pytest tests/

# Run linting
ruff check custom_components/

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Buy Me a Coffee: Support Development

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

⚠️ Disclaimer

This integration is not affiliated with, endorsed by, or connected to Kwikset or Spectrum Brands. Kwikset is a trademark of Spectrum Brands, Inc. This is an unofficial integration using an undocumented API that may change at any time

Name		Name	Last commit message	Last commit date
.github		.github
.vs		.vs
.vscode		.vscode
custom_components/kwikset		custom_components/kwikset
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DYNAMIC_DEVICE_DISCOVERY.md		DYNAMIC_DEVICE_DISCOVERY.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
INTEGRATION_QUALITY_SCALE.md		INTEGRATION_QUALITY_SCALE.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
QUICK_START.md		QUICK_START.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
hacs.json		hacs.json
info.md		info.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements_test.txt		requirements_test.txt

Latest commit

History

Folders and files

Repository files navigation

Kwikset Smart Locks for Home Assistant

🚨 Breaking Change Notice (v0.4.0)

Quick Summary:

📋 Table of Contents

✨ Features

Lock Control

Device Settings

Smart Features

Connection Modes

🔐 Supported Devices

Verified Working Models

📡 Data Updates

Polling Behavior

How It Works

Optimistic State Updates

Latency Considerations

⚠️ Known Limitations

API Limitations

Feature Limitations

Device Limitations

Secure Screen Switch

📌 Requirements

Prerequisites

Important Notes

📦 Installation

Option 1: HACS (Recommended)

Option 2: Manual Installation

⚙️ Configuration

Initial Setup

Installation Parameters

Configuration Options

Multiple Homes

🗑️ Removal

Removing the Integration

Uninstalling via HACS

Manual Uninstallation

🎛️ Entities

Lock Entity

Sensor Entities

Switch Entities

Service Actions

Lock Actions

Switch Actions

🏠 Use Cases & Automations

Example 1: Auto-Lock at Night

Example 2: Low Battery Alert

Example 3: Welcome Home Unlock

Example 4: Lock Status Dashboard Card

Example 5: Guest Access Notification

🔧 Troubleshooting

Common Issues

"Cannot connect" error during setup

"Invalid authentication" error

MFA verification code not working

"No available homes" error

Locks not appearing after setup

Lock shows "unavailable"

Actions fail with "Failed to lock/unlock"

Debug Logging

Getting Help

📊 Quality Scale Compliance

Current Status: Platinum ✅

Key Quality Features

🤝 Contributing

Development Setup

💬 Support

📄 License

⚠️ Disclaimer

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages