# Partner OAuth 接入 — 自动渠道归因

Source: https://ofox.ai/zh/docs/develop/partner-oauth

**Beta。** OAuth 模式正在灰度开放，请联系我们登记你的应用。

如果你计划把 ofox 集成进自己的产品，用户可以点击 OAuth 按钮前往 ofox 完成登录与授权，再返回你的应用。通过这种方式注册的新用户会自动计入你的 partner 渠道 —— 与他们通过你的推广链接注册完全等效。

## 如何接入

**应用仍在开发中也可以申请，不需要等产品全部完成。** OAuth 接入目前处于 Beta 阶段，登记信息需由团队确认。

1. 如果尚未加入合作伙伴计划，请先在 [Partner 页面](https://ofox.ai/zh/partner)申请；已申请或已激活的伙伴无需重复申请。
2. 将下方登记信息发送至 [hi@ofox.ai](mailto:hi@ofox.ai)，或直接回复已有的支持邮件。
3. 我们确认应用信息、回调地址和所需权限后，为你登记 OAuth 应用并绑定推广渠道，提供对应接入配置。
4. 在你的产品中完成 OAuth 2.1 接入，并验证授权、返回应用及模型调用流程。

渠道归因不需要额外拼接推广参数，由我们在登记时配置。OAuth 自身的回调地址、权限及授权流程仍需按接入配置实现。

## 登记应用需要提供什么

| 信息 | 需要说明的内容 |
|---|---|
| 应用名称与用途 | 暂定名称也可以；说明主要功能、面向的用户，以及如何使用 ofox 模型服务 |
| 应用形态 | 网页、桌面客户端、手机应用、浏览器插件或命令行工具；是否有自己的后端服务 |
| OAuth 回调地址（Redirect URI） | 授权后返回应用的完整地址；测试与正式环境请分别列出。实际登记前需确认地址，尚未确定可以先说明技术方案 |
| Partner 信息 | 申请合作伙伴计划使用的邮箱，以及推广链接或推广码；已在同一邮件中提供的内容无需重复提交 |
| 所需功能 | 是否需要调用模型、显示余额或用量、读取组织信息、保持登录；直接描述需求即可，无需自行选择所有权限 |
| 产品链接与 Logo（可后补） | 有官网、项目仓库、演示页面或截图可一并提供；产品尚未上线可先写简单介绍，Logo 可后续补充 |

回调地址需要与登记值**完全一致**，不支持通配符；协议、域名、端口、路径以及末尾的 `/` 都需要保持一致。网页正式环境建议使用 HTTPS。桌面、手机或本地开发场景，请在登记时说明回调方式。

不需要为了发起接入咨询先提交完整源码或开发完成的产品。请勿在申请邮件中发送密码、API Key、Client Secret 或 Access Token。

可复制以下模板，暂未确定的项目标注“待确认”：

```text
应用名称：
应用用途 / 面向用户：
应用形态 / 是否有后端：
测试环境回调地址：
正式环境回调地址：
Partner 申请邮箱：
Partner 推广链接或推广码：
需要的功能：
产品链接 / 介绍（如有）：
Logo（如有）：
```

## 接入前需要确认

- **客户端类型**：有后端并能安全保管密钥的应用，与直接在浏览器、桌面或手机中运行的应用，接入配置不同。请说明实际架构；不要把 Client Secret 放入前端代码或分发给用户的安装包。
- **权限范围**：仅申请产品实际需要的权限。调用模型需要 `llm.invoke`；其他功能按需求确认，获准的权限以实际授权结果为准。
- **联调信息**：登记后按提供的配置接入；遇到问题请提供操作步骤、脱敏后的错误信息和发生时间，不要发送令牌或密钥。

## 哪些消耗会被计入

**仅限新注册用户。** 当一个还没有 ofox 账号的用户点击你的 OAuth 按钮，他会被带到 ofox 登录页，切换到注册流程并完成注册 —— 绑定在注册那一刻建立。此后他的充值与消费都走正常的 partner 返佣结算。

**已有 ofox 账号的用户，其归属永不改变。** 授权你的应用不会改变它 —— 即使该用户从未被任何 partner 绑定过也一样。这既适用于已绑定其他 partner 的用户，也适用于完全没有绑定的用户。

这是刻意设计：推广绑定对一个账号是终身且排他的。允许改绑等于让一个 partner 抢走另一个 partner 拉来的用户。

## 首次调用的 scope

刚注册完拿到的 access token，可能还不包含 `llm.invoke`。

`llm.invoke` 只发给邮箱已验证的用户。而注册完成那一刻邮箱是否已验证，取决于用户选了哪种注册方式：

| 注册方式 | 完成时邮箱是否已验证 | 首个 token 里有无 `llm.invoke` |
|---|---|---|
| 免密登录链接 | 是 —— 点开链接本身就是验证 | 有 |
| 邮箱 + 密码 | 否 | **被剔除**，直到验证完成 |

scope 被剔除时 token 请求仍会成功 —— 响应里的 `scope` 字段列出的是**实际发放**的集合（RFC 6749 §3.3）。**请读这个字段，不要假设申请什么就拿到什么。** 没有 `llm.invoke` 去调 LLM API 会返回 `403 insufficient_scope`。

用户完成邮箱验证后，重新获取（或刷新）token，`llm.invoke` 就会包含在内。

## 返佣

被归因的用户按标准分层返佣结算（最高 9%），依据实际 API 用量计算。满 $50 起提，按月结算。当前条款见 [Partner 页面](https://ofox.ai/zh/partner)。