外观
Sub2API:读取 Codex OAuth 与续签后台会话
本站 plus池 的账号配置由 Sub2API 管理。本文说明如何读取指定账号的 Codex OAuth,以及长期接入时如何续签用于调用管理接口的后台会话。
先区分两套授权信息
接口一返回目标账号的 Codex OAuth;接口二更新调用方的后台管理员会话。 两者虽然都有 access_token、refresh_token 字段,但所属对象、字段路径和用途不同,不能互换。续签后台会话不会更新账号的 Codex OAuth。
仅限授权使用,勿滥用
Sub2API 接入地址、后台会话凭据及可读取的账号范围,请联系管理员。仅处理获准的账号,不遍历、批量导出、频繁续签或共享凭据。普通 FQHX 调用仍使用本站令牌,无需获取这些管理凭据。
授权信息对照
| 授权信息 | 来源与字段位置 | 用途 |
|---|---|---|
| 后台管理员访问令牌 | 管理员提供;续签后为接口二的 data.access_token | 放入接口一的 Authorization: Bearer …,认证管理接口调用方 |
| 后台管理员刷新令牌 | 管理员提供,须与访问令牌属于同一后台会话;续签后为接口二的 data.refresh_token | 放入接口二请求体,换取新的一对后台令牌 |
| 目标账号 Codex 访问令牌 | 接口一的 data.accounts 对应账号下的 credentials.access_token | 用于获准的上游 Codex OAuth 接入场景 |
| 目标账号 Codex 刷新令牌 | 接口一的 credentials.refresh_token,可能缺失 | 属于目标账号的上游 OAuth;不能提交给本文的后台续签接口 |
判断令牌类型时,同时核对所属接口和字段路径,不能只看字段名称。 FQHX 令牌、目标账号的 Codex 访问令牌或任意刷新令牌,均不能代替后台管理员访问令牌调用接口一。
接入准备与接口概览
联系管理员取得的信息
| 信息 | 接入要求 |
|---|---|
| Sub2API 接入地址 | 必需;由管理员私下提供,不包含接口路径 |
| 获准读取的本地账号 ID | 必需;Sub2API 本地 Codex 账号的数字 ID,不是 ChatGPT Account ID,也不是 FQHX 渠道、分组、用户或令牌 ID |
| 当前后台管理员访问令牌 | 读取时必需;取得原始令牌后,在请求头中自行添加 Bearer 前缀 |
| 同一后台会话的当前刷新令牌 | 长期自动接入时必需;确认由接入服务统一维护该会话,避免管理员与服务并发轮换 |
| 后台访问令牌到期信息 | 长期自动接入时一并取得到期时间,或签发时间与 expires_in,供续签调度使用 |
仅读取一次时,前三项即可。长期接入还应取得配套的后台刷新令牌与到期信息,并在交付时确认令牌仍有效;有效期从签发时计算,不能从交付时重新起算。
两个接口
| 接口 | 请求 | 使用的授权信息 | 返回内容 |
|---|---|---|---|
| 接口一:读取账号 Codex OAuth | GET /api/v1/admin/accounts/data | 请求头中的后台管理员访问令牌 | 目标账号当前保存的 Codex OAuth |
| 接口二:续签后台管理员会话 | POST /api/v1/auth/refresh | 请求体中的后台管理员刷新令牌 | 新的一对后台管理员令牌及访问令牌有效期 |
以下为 HTTP/1.1 请求示例。使用 HTTPS,在本机 HTTP 客户端中填写管理员提供的地址与凭据;Host 仅为占位符。将 {account_id} 替换为本次获准读取的数字账号 ID,不扩大账号范围。
接口一:读取账号 Codex OAuth
GET /api/v1/admin/accounts/data
读取指定账号已保存在 Sub2API 中的 OAuth 数据。该接口不会刷新令牌,也不会验证返回的 Codex 访问令牌在上游是否有效。
请求参数与认证
| 位置 | 参数 | 填写方式 |
|---|---|---|
| Query | ids | 必填,填写管理员提供的本地账号 ID;本文按读取单个账号说明 |
| Query | include_proxies | 建议固定 false,不额外导出代理信息,无需管理员另外提供 |
| Header | Authorization | Bearer 加当前有效的后台管理员访问令牌,中间保留一个空格 |
请求体:无。
HTTP 请求示例
http
GET /api/v1/admin/accounts/data?ids={account_id}&include_proxies=false HTTP/1.1
Host: <联系管理员获取>
Authorization: Bearer <当前后台管理员访问令牌>
Accept: application/json成功响应与字段含义
确认 HTTP 状态成功且业务响应 code=0 后,按账号 ID 从 data.accounts 中选择目标账号,读取其 credentials。以下只展示相关字段,结构经过裁剪,凭据值均为占位内容;refresh_token 可能缺失:
json
{
"code": 0,
"data": {
"accounts": [
{
"credentials": {
"access_token": "<目标账号的Codex访问令牌>",
"refresh_token": "<目标账号的Codex刷新令牌,可能缺失>",
"expires_at": "<目标账号的Codex访问令牌到期时间>"
}
}
]
}
}字段(位于目标账号的 credentials 中) | 含义与处理 |
|---|---|
access_token | 目标账号的上游 Codex 访问令牌,与请求头中的后台管理员访问令牌不同 |
refresh_token | 目标账号的上游 Codex 刷新令牌,可能缺失;不能用于接口二 |
expires_at | Codex 访问令牌到期信息,可能是 RFC3339 日期字符串、Unix 秒时间戳字符串或数字,按实际格式解析 |
读取不会延长 Codex 令牌有效期,不能用后台令牌的 24 小时/30 天有效期推算它。接口一也不能读取或找回后台管理员刷新令牌。
接口二:续签后台管理员会话
POST /api/v1/auth/refresh
使用当前后台会话的刷新令牌,获取新的一对后台管理员令牌,供后续继续调用管理接口。此接口不针对某个 Codex 账号,不接收账号 ID,也不更新接口一返回的 Codex OAuth。
后台令牌有效期
以下有效期依据维护方 2026-11-12 更新的本地接入文档,适用于该文档所述部署;访问令牌有效期以实际响应为准。
| 后台令牌 | 有效期 | 起算与失效规则 |
|---|---|---|
| 后台管理员访问令牌 | 24 小时,续签响应 expires_in=86400 秒 | 从本次签发起算;也可能因注销、改密或会话撤销而提前失效 |
| 后台管理员刷新令牌 | 30 天 | 从这一枚令牌签发起算;成功轮换后旧值作废,也可能随会话提前失效 |
expires_in 仅表示后台访问令牌的有效期,不表示后台刷新令牌或账号 Codex OAuth 的有效期。
请求参数与认证
| 位置 | 参数 | 填写方式 |
|---|---|---|
| Header | Content-Type | application/json |
| Body | refresh_token | 必填字符串,当前后台管理员刷新令牌;使用最新轮换保存的值 |
此接口通过请求体中的后台刷新令牌续签,不要求提供仍有效的后台访问令牌。不要提交接口一导出的 Codex 刷新令牌。
HTTP 请求示例
http
POST /api/v1/auth/refresh HTTP/1.1
Host: <联系管理员获取>
Content-Type: application/json
Accept: application/json
{
"refresh_token": "<当前后台管理员刷新令牌>"
}成功响应与保存要求
以下为成功响应的关键字段,所有令牌值均为占位内容:
json
{
"code": 0,
"data": {
"access_token": "<新的后台管理员访问令牌>",
"refresh_token": "<新的后台管理员刷新令牌>",
"expires_in": 86400,
"token_type": "Bearer"
}
}| 响应字段 | 含义与处理 |
|---|---|
data.access_token | 新的后台管理员访问令牌,后续调用接口一时使用 |
data.refresh_token | 新的后台管理员刷新令牌,下次续签时使用;已直接返回,无需额外获取 |
data.expires_in | 本次后台访问令牌有效秒数,用于更新到期时间与续签计划 |
data.token_type | 访问令牌认证类型,示例为 Bearer |
确认 HTTP 成功、code=0 且两枚新令牌均非空后,将新的后台访问令牌、刷新令牌及到期信息作为一组同时保存,避免出现新旧令牌混用。
正常轮换后,旧后台刷新令牌作废,不能继续使用到原定第 30 天;新刷新令牌从本次签发起重新计算有效期。后续直接使用保存的新值,不需要每次再联系管理员索取。
这次续签只更新后台会话。 接口一读取出的账号 Codex 访问令牌、刷新令牌和到期时间,不会因此改变。
长期接入的调用顺序
- 向管理员取得接入地址、获准读取的本地账号 ID、当前后台访问令牌,以及配套的后台刷新令牌和到期信息。
- 使用后台访问令牌调用接口一,读取并核对目标账号的 Codex OAuth;将账号凭据与后台会话凭据分别保存。
- 后台访问令牌剩余有效期不超过 5 分钟时,用当前后台刷新令牌调用接口二。该时间用于后台会话续签调度,与 Codex 令牌到期时间无关。
- 检查 HTTP 状态、
code及两枚新令牌;将新后台令牌对和到期信息一并保存,再更新内存中的调用凭据。 - 后续使用新的后台访问令牌继续读取同一个获准账号;下次续签使用新后台刷新令牌。
同一后台会话应串行续签,避免多个进程或管理员同时使用同一枚旧刷新令牌。若续签响应丢失,旧刷新令牌可能已被消耗;先检查共享存储是否已保存新令牌对,无法恢复时重新登录后台或联系管理员,不要无限重试旧值。
错误处理与凭据保护
| 情况 | 处理方式 |
|---|---|
| 接口一后台认证失败或权限不足 | 检查使用的是否为当前后台访问令牌;按后台会话状态续签或联系管理员处理权限 |
| 读取结果没有目标账号或凭据 | 核对管理员提供的账号 ID 和保存情况,不改为遍历其他账号 |
| 目标账号 Codex 访问令牌过期或授权撤销 | 联系管理员处理账号授权;调用接口二不能修复账号的上游 OAuth |
| 后台刷新令牌失效、已轮换或会话撤销 | 使用已保存的最新令牌对;无法恢复时重新登录后台或联系管理员 |
| 续签返回失败、缺少任一新令牌 | 不覆盖当前保存的凭据,不按成功流程继续;结合错误信息处理,避免盲目重试旧刷新令牌 |
| 续签成功后仍在使用旧后台访问令牌 | 检查是否已成对保存新令牌并更新调用方,避免进程继续读取旧缓存 |
只在受信任的环境中通过 HTTPS 处理凭据,不将完整响应、令牌或认证请求头上传到共享工作区、聊天、截图、工单或公开仓库。排查记录仅保留脱敏后的时间、账号 ID、状态及错误信息,勿滥用管理访问权限。
资料依据:《Sub2API_获取Codex_OAuth授权信息_API接入文档.md》(维护方更新:2026-11-12)。本文按本地文档整理,未执行接口调用验证。