Skip to content

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 OAuthGET /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 访问令牌在上游是否有效。

请求参数与认证 ​

位置参数填写方式
Queryids必填,填写管理员提供的本地账号 ID;本文按读取单个账号说明
Queryinclude_proxies建议固定 false,不额外导出代理信息,无需管理员另外提供
HeaderAuthorizationBearer 加当前有效的后台管理员访问令牌,中间保留一个空格

请求体:无。

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_atCodex 访问令牌到期信息,可能是 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 的有效期。

请求参数与认证 ​

位置参数填写方式
HeaderContent-Typeapplication/json
Bodyrefresh_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 访问令牌、刷新令牌和到期时间,不会因此改变。

长期接入的调用顺序 ​

  1. 向管理员取得接入地址、获准读取的本地账号 ID、当前后台访问令牌,以及配套的后台刷新令牌和到期信息。
  2. 使用后台访问令牌调用接口一,读取并核对目标账号的 Codex OAuth;将账号凭据与后台会话凭据分别保存。
  3. 后台访问令牌剩余有效期不超过 5 分钟时,用当前后台刷新令牌调用接口二。该时间用于后台会话续签调度,与 Codex 令牌到期时间无关。
  4. 检查 HTTP 状态、code 及两枚新令牌;将新后台令牌对和到期信息一并保存,再更新内存中的调用凭据。
  5. 后续使用新的后台访问令牌继续读取同一个获准账号;下次续签使用新后台刷新令牌。

同一后台会话应串行续签,避免多个进程或管理员同时使用同一枚旧刷新令牌。若续签响应丢失,旧刷新令牌可能已被消耗;先检查共享存储是否已保存新令牌对,无法恢复时重新登录后台或联系管理员,不要无限重试旧值。

错误处理与凭据保护 ​

情况处理方式
接口一后台认证失败或权限不足检查使用的是否为当前后台访问令牌;按后台会话状态续签或联系管理员处理权限
读取结果没有目标账号或凭据核对管理员提供的账号 ID 和保存情况,不改为遍历其他账号
目标账号 Codex 访问令牌过期或授权撤销联系管理员处理账号授权;调用接口二不能修复账号的上游 OAuth
后台刷新令牌失效、已轮换或会话撤销使用已保存的最新令牌对;无法恢复时重新登录后台或联系管理员
续签返回失败、缺少任一新令牌不覆盖当前保存的凭据,不按成功流程继续;结合错误信息处理,避免盲目重试旧刷新令牌
续签成功后仍在使用旧后台访问令牌检查是否已成对保存新令牌并更新调用方,避免进程继续读取旧缓存

只在受信任的环境中通过 HTTPS 处理凭据,不将完整响应、令牌或认证请求头上传到共享工作区、聊天、截图、工单或公开仓库。排查记录仅保留脱敏后的时间、账号 ID、状态及错误信息,勿滥用管理访问权限。

资料依据:《Sub2API_获取Codex_OAuth授权信息_API接入文档.md》(维护方更新:2026-11-12)。本文按本地文档整理,未执行接口调用验证。

本站提供 FQHX 接入说明;模型能力与审核规则以上游平台最新规定为准。