用途
terra-auth 用于统一管理 Terra API 的身份验证与凭据，帮助开发者在测试、预发布（staging）和生产三套环境之间安全切换凭证，并完成与 Terra 集成相关的认证操作。它面向需要接入 Terra 可穿戴设备数据平台的 Python 后端开发场景。
主要能力
- 按环境管理凭据：凭据存储在环境专属的 .env 文件中，测试环境为 .env.terra.testing，预发布为 .env.terra.staging，生产为 .env.terra.production。可通过 python-dotenv 的 load_dotenv 加载指定环境，再读取 TERRA_DEV_ID 与 TERRA_API_KEY。也可使用辅助函数 get_terra_client("testing") 直接获取对应环境的客户端。
- 初始化 Python SDK：通过 from terra import Terra 创建客户端，传入 dev_id 与 api_key，并用 client.integrations.fetch() 验证连接。
- 生成认证部件会话（generate-widget-session）：为终端用户创建认证 Widget 的 URL，需提供 reference_id、成功回调地址与失败回调地址，可选过滤指定提供商（如 FITBIT、GARMIN）。返回结果包含 url、session_id 与 expires_at。
- 生成移动令牌（generate-mobile-token）：为移动 SDK 初始化生成认证令牌。文档特别说明该令牌是针对账户生成而非按用户生成，用户识别应通过移动 SDK 初始化时传入的 reference_id 完成。令牌有效期为 180 秒（3 分钟），且为一次性使用。
- 注销用户（deauthenticate-user）：移除用户并撤销其数据访问权限，返回成功状态。
- 列出集成（list-integrations）：获取所有可用的提供商集成，返回名称、资源与 logo 地址等信息。
- REST API 调用规范：所有 REST 调用需携带 dev-id、x-api-key 与 Content-Type: application/json 请求头，文档提供了对应的 cURL 示例。
- 环境与端点信息：列出生产 API（https://api.tryterra.co）、Widget（https://widget.tryterra.co）与流式接口（wss://streaming.tryterra.co）的基础地址。
- 令牌生命周期说明：Widget 会话 15 分钟；移动 SDK 令牌 3 分钟且一次性；OAuth 令牌由 Terra 自动刷新；API 密钥不自动过期，必要时手工轮换。
- 安全最佳实践：不在前端或移动应用中暴露 API 密钥；使用环境变量保存凭据；移动令牌仅在后端生成；所有重定向 URL 使用 HTTPS；密钥泄露后及时轮换（联系 Terra 支持）；不同环境使用不同密钥。
- Webhook 签名密钥：每个环境有独立的签名密钥，可在 Terra Dashboard 的 Destinations → Webhooks 中找到，用于 HMAC-SHA256 签名验证（具体实现见 terra-webhooks 技能）。
使用方式
以 Python 为主。可通过 python-dotenv 加载环境文件后读取变量，或使用脚本提供的 get_terra_client 辅助函数按环境名获取客户端。SDK 初始化后即可调用认证、集成相关方法。移动令牌需通过后端接口下发，并同时返回用于 SDK 初始化的 reference_id。REST 方式则按指定请求头调用 API。
适用场景
适用于在 Python 后端搭建 Terra 集成的开发者，尤其是需要在多环境间隔离凭据、为终端用户创建 Widget 认证流程、为移动端下发一次性令牌、注销用户并撤销数据访问，以及查询可用可穿戴设备提供商的场景。
限制与注意
文档未提供 Terra 的收费、价格、平台覆盖范围与具体效果信息。移动令牌有效期短且仅可使用一次，需按需重新生成。部分内容（如 Webhook 签名验证实现）需参考关联技能，本文档未展开。