用途：为 BambooHR 集成选择并配置认证方式。OAuth 2.0 是官方推荐的合作伙伴集成路径；API 密钥适合内部工具或原型，前提是其所属用户的权限与密钥生命周期可接受。
主要能力：区分合作伙伴/多租户与内部/单租户集成并记录认证决策；从客户 BambooHR URL 推导租户子域；实现授权码交换、state 校验、加密令牌持久化、轮换与刷新失败后的重新授权；为 API 密钥指定专用所有者、记录字段权限并制定轮换与吊销流程。
必要用法：租户 API 主机为 https://{company-subdomain}.bamboohr.com；授权端点为 https://{company-subdomain}.bamboohr.com/authorize.php；令牌端点为 POST https://{company-subdomain}.bamboohr.com/token.php?request=token。API 密钥请求使用 HTTP Basic 认证，密钥作为用户名，x 作为密码。OAuth 需注册 HTTPS 重定向 URI、生成高熵 state 并绑定会话，服务端交换代码，将访问令牌、刷新令牌、过期时间、租户、主体与授权范围存入加密的租户级记录。API 密钥应存入部署密钥管理器，不得出现在 .env.example、日志、shell 历史、测试夹具或客户端包中。
适用场景：注册合作伙伴集成、接入令牌存储与轮换、内部工具认证配置。
限制：该技能不授权浏览器同意、创建凭据、安装包或远程修改密钥；注册 OAuth 应用、更改重定向 URI、创建或轮换 API 密钥、写入部署密钥、对生产租户测试均需明确批准。截至 2026-09-11，文档所述 bamboohr-sdk 发行版在公共 PyPI 上不可发现，安装前需核实注册表或使用已批准的提交固定版本。SDK 不会为应用持久化刷新后的令牌。错误处理：state 不匹配立即拒绝并重新开始；401 在已配置时刷新一次，否则视为无效；403 检查字段权限而非盲目扩大；刷新失败停止有限重试、保留最后有效记录并要求重新授权。