Connecting Your Home Assistant Hub

Connecting Home Assistant to Staykey

Staykey integrates with Home Assistant to provide fast, reliable control of your smart devices. There are two ways to connect — the Staykey plugin (recommended) handles everything automatically, or you can use a direct connection with a public URL.

Option 1: Staykey Plugin (Recommended)

The Staykey plugin runs inside Home Assistant and opens a secure outbound connection to Staykey. This is the easiest and most reliable way to connect — no public URL, no port forwarding, no subscription required.

What you need:

• Home Assistant installed and running
• The Staykey plugin installed via HACS
• A gateway token from Staykey (found in your property's integration settings)

How to connect:

1. Install the Staykey plugin — Follow the installation guide to install via HACS.
2. Get your gateway token — In Staykey, go to Properties → Manage → Manage Property → Integrations and add a Home Assistant integration. Copy the gateway token provided.
3. Configure the plugin — In Home Assistant, go to Settings → Devices & Services → Add Integration → Staykey and enter your gateway token.
4. Select devices — In Staykey, click Edit under Devices and choose which locks, thermostats, switches, or other devices Staykey should manage.

The plugin connects automatically. You should see a "Connected" status within seconds.

Why the plugin is recommended:

• No need to expose Home Assistant to the internet
• Faster device control (commands execute locally inside Home Assistant)
• Real-time state streaming (no polling delay)
• Access code verification (the plugin confirms codes were written to your lock)
• Device health data capture (battery levels, connectivity — dashboard alerts coming soon)
• Automatic reconnection if your internet drops

Option 2: Direct Connection (Public URL)

If you prefer not to install the plugin, you can connect Staykey directly to your Home Assistant via its REST API. This requires a publicly accessible URL.

What you need:

• Home Assistant installed and running
• A publicly accessible Home Assistant URL — Staykey connects to your hub over the internet, so local-only URLs like http://homeassistant.local:8123 won't work
• A Staykey account with at least one property added

Making Home Assistant publicly accessible:

You'll need to expose your Home Assistant instance so Staykey can reach it. Choose one of these methods:

Nabu Casa (Home Assistant Cloud)

• Easiest setup (~5 minutes)
• $6.50/month subscription
• Supports Home Assistant development

Tailscale Funnel

• Free option
• Good for technical users
• Takes ~15 minutes to set up

How to connect:

1. Open Integrations: In Staykey, go to Properties → Manage → Manage Property → Integrations for the property you're connecting.
2. Add Home Assistant: Click Add Integration and choose Home Assistant.
3. Enter your public URL: Use your Nabu Casa URL (e.g., https://xxxxxxxxxx.ui.nabu.casa) or Tailscale Funnel URL (e.g., https://your-hostname.tail-scale.ts.net).
4. Create a Long-Lived Access Token: In Home Assistant, go to Profile → Security → Long-Lived Access Tokens and generate a new token.
5. Save the token securely: Copy it to a password manager immediately — Home Assistant won't show it again.
6. Connect: Paste the token into Staykey and click Connect.
7. Select devices: Click Edit under Devices and choose which locks, thermostats, switches, or other devices Staykey should manage.

Token security (direct connection only)

Long-Lived Access Tokens are sensitive. Treat them like passwords:

• Store tokens in a password manager
• Rotate tokens if they're ever exposed
• Remove unused tokens from your Home Assistant profile
• Use a dedicated token for Staykey (don't share tokens across services)

Verify your connection

After connecting (via either method), you should see your Home Assistant devices listed in Staykey. If devices don't appear:

• Plugin users: Check that the plugin shows "Connected" in Home Assistant under Settings → Devices & Services
• Direct connection users: Verify your Home Assistant URL is publicly accessible (try opening it in a browser from your phone with WiFi off)
• Check that the access token hasn't expired or been deleted (direct connection)
• Ensure the devices are available in Home Assistant itself

Troubleshooting

• Plugin not connecting: Check internet access and verify the gateway token is correct. See the plugin troubleshooting guide.
• "Cannot connect" error (direct): Double-check your public URL is correct and accessible from outside your network.
• Devices not appearing: Refresh the integration in Staykey and re-run device discovery.
• Token errors (direct): Generate a new Long-Lived Access Token and update it in Staykey.

Need more help? Check our device connection troubleshooting guide.