鉴权

百居易 OpenAPI v3 支持两种鉴权方式。两者访问的是同一套接口、同一份数据，区别在于 谁来发起集成：

你的身份	使用方式	原因
自己是百居易房东，集成自家账号	Access Token	最简单，一个请求头搞定，没有授权流程
软件合作伙伴，做的产品给多个百居易房东使用	OAuth 2.0	每个房东各自授权，不需要把自己的 Token 给你
MCP 客户端（Claude Desktop、Cursor、自研 LLM Agent）	OAuth 2.0 + PKCE，通过 `/mcp` 端点	MCP 传输层会自动完成 OAuth 握手

1. Access 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	能做什么
`read-only`	仅 `GET` 请求。一旦写操作就会返回 `401 Not authorized for this action`。
`writable`	全部接口可用。请审慎使用并定期轮换。

Scope 在创建时确定，不可修改。需要升级权限时，创建新 Token 并撤销旧的。

Access Token 自身不会过期，直到：

集成方在收到 401 时应当有合理的提示重新授权路径。

如果你是已被审核通过的软件合作伙伴（拿到了百居易的 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 概览。

无论是 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.`	仅 OAuth：`client_secret` / `code_verifier` 校验失败次数过多（10 分钟内 >10 次），稍后再试。

HTTP 状态码恒为 200，业务结果一律看响应体的 error_code。完整错误码请见错误码。