鉴权
百居易 OpenAPI v3 支持两种鉴权方式。两者访问的是同一套接口、同一份数据,区别在于 谁来发起集成:
| 你的身份 | 使用方式 | 原因 |
|---|---|---|
| 自己是百居易房东,集成自家账号 | Access Token | 最简单,一个请求头搞定,没有授权流程 |
| 经审核的软件合作伙伴,已持有百居易发放的 OAuth 凭据 | OAuth 2.0 | 每个房东各自授权,不需要把自己的 Token 给你 |
| MCP 客户端(Claude Desktop、Cursor、自研 LLM Agent) | OAuth 2.0 + PKCE,通过 /mcp 端点 | MCP 传输层会自动完成 OAuth 握手 |
1. Access Token
如何获取
房东在百居易后台自行创建:
- 登录 https://www.myhostex.com/app/dashboard。
- 打开 OpenAPI 设置页。
- 点击 + 新增,命名 Token,选择权限(只读 / 可写)。
如何使用
每次请求都在 Hostex-Access-Token 请求头里携带 Token:
GET /v3/properties HTTP/1.1
Host: api.myhostex.com
Hostex-Access-Token: AbCdEf1234567890...
服务端两种请求头都接受——先读 Hostex-Access-Token,再回退到标准的 Authorization: Bearer …。建议优先用 Hostex-Access-Token,避免和 OAuth Bearer Token 混淆。
权限范围(scope)
| Scope | 能做什么 |
|---|---|
read-only | 仅 GET 请求。一旦写操作就会返回 401 Not authorized for this action。 |
writable | 全部接口可用。请审慎使用并定期轮换。 |
Scope 在创建时确定,不可修改。需要升级权限时,创建新 Token 并撤销旧的。
生命周期与撤销
Access Token 自身不会过期,直到:
- 房东在 OpenAPI 设置页删除它,或
- 房东订阅过期(此时调用会返回
420 Subscription expired,Token 本身仍然有效,房东续费后即可恢复),或 - 房东注销百居易账号。
集成方在收到 401 时应当有合理的提示重新授权路径。
2. OAuth 2.0 Bearer Token
如果你是已被审核通过的软件合作伙伴(拿到了百居易的 client_id),需要先用授权码换取 Bearer Token,然后通过标准的 Authorization 请求头携带:
GET /v3/properties HTTP/1.1
Host: api.myhostex.com
Authorization: Bearer eyJhbGciOi...
OAuth Token 7 天过期。请在过期前使用配套的 refresh token 续期。完整流程与 scope 见 OAuth 概览。轮换后,在默认 60 秒宽限期内重复使用旧 refresh token,只要新令牌记录仍存在,就返回同一对新令牌;宽限期结束或新令牌记录被撤销后,旧 refresh token 无效。请原子保存返回的令牌对。
服务端如何识别鉴权方式
无论是 Access Token 还是 OAuth Bearer Token,服务端最终都解析到同一个 operator(房东账号)。Webhook、审计日志、错误响应都 不会区分 当前请求是哪一种鉴权方式——同一笔请求里两者等价。
鉴权相关错误码
响应体 error_code | 触发场景 |
|---|---|
401 Invalid access token | 请求头缺失、Token 已删除、Token 不存在、Token 与该域名不匹配。 |
401 Not authorized for this action | Token 是只读但执行了写操作。请重新创建可写 Token。 |
420 Subscription expired | 百居易订阅已过期。Token 本身没问题,房东续费即可。 |
420 Basic edition does not support this feature | 房东目前为基础版,OpenAPI 需要 Pro 版本。 |
429 Too many attempts. | POST /oauth/authorizations 的凭据失败(未知客户端、client_secret / code_verifier 校验失败)计数大于 10,或独立的无效授权码 / refresh token 失败计数达到配置上限(默认 200)时拒绝请求;公共客户端不同的无效 refresh token 默认达到 30 个也会拒绝。均按 client_id、grant_type 和请求 IP 分桶(IPv6 按 /64 归组);窗口从第一次失败起固定计算,凭据失败为 600 秒,grant 失败默认为 600 秒,后续失败不续期。请退避,详见 错误码。 |
HTTP 状态码恒为
200,业务结果一律看响应体的error_code。完整错误码请见 错误码。
安全清单
- 永远不要把完整 Token 写进日志,只记 API 返回的
request_id。 - 团队成员离职后及时轮换 Token。
- 只读够用的场景就用只读 scope,能不开写就别开。
- 仅通过 HTTPS 发送请求。百居易拒绝明文 HTTP。
