HomeAssist 设置 API

简介

HomeAssist 是一个面向智能家居设备的统一控制平台。通过 HomeAssist API，开发者可以远程控制灯光、温控器、门锁、摄像头等设备，并获取设备状态信息。

本页面提供 API 的基本设置方法、认证流程、调用示例及常见问题解答，帮助您快速上手。

API 基础信息

• 基础 URL： https://api.homeassist.dev/v1
• 请求格式： JSON
• 响应格式： JSON
• 认证方式： Bearer Token（通过 OAuth 2.0 获取）

获取访问令牌

首先，您需要在 HomeAssist 开发者平台 注册应用，获取 client_id 和 client_secret。

然后通过以下请求获取访问令牌：

POST https://auth.homeassist.dev/oauth/token

Content-Type: application/x-www-form-urlencoded



grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

成功响应示例：

{

  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",

  "token_type": "Bearer",

  "expires_in": 3600

}

调用设备控制 API

使用获取到的 access_token 调用设备接口。例如，打开客厅灯：

POST /devices/living_room_light/actions

Host: api.homeassist.dev

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Content-Type: application/json



{

  "command": "turn_on"

}

常见错误码

• 400 Bad Request：请求参数错误
• 401 Unauthorized：无效或缺失访问令牌
• 403 Forbidden：无权限操作该设备
• 404 Not Found：设备不存在
• 429 Too Many Requests：请求频率超限

安全建议

• 不要在前端代码中硬编码 client_secret
• 使用 HTTPS 加密所有 API 请求
• 定期轮换访问令牌
• 限制 API 密钥的权限范围

开始你的项目

准备好开始集成 HomeAssist 了吗？