鉴权

鉴权

百居易 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

如何获取

房东在百居易后台自行创建:

  1. 登录 https://www.myhostex.com/app/dashboard。
  2. 打开 OpenAPI 设置页。
  3. 点击 + 新增,命名 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 actionToken 是只读但执行了写操作。请重新创建可写 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。