OpenAI API key 过期策略详解：expires_in_seconds、组织级 policy 与自动化密钥治理

Service Account API key 的过期语义，在 2026-09-09 这一天完成了从"可选字段"到"策略治理"的升级。openai-python v3.11.0 与 openai-node v7.13.0（均于当日 15:30 UTC 前后发布，release notes 标题分别为 "Add expiration controls for service account keys" / "Add API key expiration controls"）给 expires_in_seconds 加上了硬边界和组织级 policy 约束——"key 永不过期"从此不再是默认的最终状态，而是"还没有 policy 要求你过期"的临时状态。

本文事实全部来自 2026-09-10 当日重抓的两包 release notes、PR diff 与 v3.11.0 tag 源码（引用清单见文末）；OpenAI 官方文档域当日对本站 403，涉及管理界面操作路径的表述一律不做超出类型层证据的断言。

1. 概述：这次升级改了什么

OpenAI API key 过期策略指 2026-09-09 起 Service Account API key 的过期语义：创建服务账号时可用 expires_in_seconds（1 到 31536000 秒）给初始 key 设寿命；组织或项目级 policy 可要求 key 必须过期并可设最大生命周期。

时间线分两步，容易混淆：

第一步是"你能传这个字段"，第二步是"你的组织可以强制你传、并限制你传多大"。两包版本号不一一对应，这是 OpenAI 双 SDK 的常态。

2. expires_in_seconds 的完整语义

v3.11.0 的 ServiceAccountCreateParams（src/openai/types/admin/organization/projects/service_account_create_params.py）里，这个参数的 docstring 值得整段读：

Number of seconds until the initial API key expires. If omitted or null, the key does not expire unless the effective organization or project policy requires an expiration. When a policy sets a maximum lifetime, this value must be provided and must not exceed that limit. A non-null value cannot be used when create_service_account_only is true.

拆成四条规则：

1. 显式传值：初始 key 在 expires_in_seconds 秒后过期，取值 1 到 31536000（365 天）——schema 硬校验（minimum: 1 / maximum: 31536000），超出直接被拒。
2. 不传或 null：key 不过期——但仅当没有生效的组织/项目级 policy 要求过期。policy 存在时，即使你不传，key 也会按 policy 过期。
3. policy 设了最大生命周期：此时 expires_in_seconds 从可选项变成必填项，且值不得超过 policy 上限。
4. 与 create_service_account_only 互斥：create_service_account_only: true 表示创建不带初始 key 的服务账号——没有初始 key，自然没有"初始 key 的过期时间"可设，此时传非 null 值会被拒绝。

一句话总结：policy 是新的最高优先级。你的代码传不传值，都要先回答"我的组织有没有设 policy、上限是多少"。

3. 组织/项目级 policy：SDK 类型层能确认与不能确认的

能确认的（类型层有证据）：policy 的效果——它能让"不传值"的 key 过期、能给 expires_in_seconds 设上限、能把可选项变成必填。

不能确认的（类型层无证据，截至 2026-09-10 核对）：policy 的管理端点。两包 SDK 里没有创建、查询、修改 policy 的资源与方法。按现有证据，policy 通过 OpenAI 管理界面设置；SDK 类型里没有相反证据，也没有佐证它有 API。等它的端点出现在类型层，本站会跟进。

对多团队组织这是个典型的平台治理信号：安全团队可以在组织层面强制"所有 service account key 最长活 N 天"，业务代码不改一行就自动被约束——传了超限值会被拒，不传值会按 policy 过期。

4. 代码示例

4.1 创建带过期时间的 Service Account（Python）

from openai import OpenAI

client = OpenAI()

sa = client.admin.organization.projects.service_accounts.create(
    project_id="prj_xxx",              # 占位示例
    name="ci-runner",
    expires_in_seconds=60 * 60 * 24 * 90,   # 90 天（7776000 秒，合法区间 1..31536000）
)
print(sa.expires_at)   # Unix 时间戳（秒）；null 表示不过期

4.2 同一操作的 Node 版本

import OpenAI from 'openai';

const client = new OpenAI();

const sa = await client.admin.organization.projects.serviceAccounts.create({
  project_id: 'prj_xxx',        // 占位示例
  name: 'ci-runner',
  expires_in_seconds: 60 * 60 * 24 * 90,
});
console.log(sa.expires_at);     // Unix timestamp (seconds); null = never expires

4.3 审计存量 key 的过期时间（Python）

keys = client.admin.organization.projects.api_keys.list(project_id="prj_xxx")
for k in keys.data:
    print(k.id, k.expires_at)   # v3.11.0 起 project API key 对象携带 expires_at

三段代码均为 SDK 源码核对版（对照 v3.11.0 类型定义逐字段核对），未在真实 key 下实跑；project_id 等占位值替换成你自己的资源 ID。

5. 运维清单：把 policy 语义用起来

• CI / 自动化场景：key 寿命与部署节奏对齐——流水线用的 key 传 30 天（2592000 秒），配合轮换日历；不要用 365 天上限去偷懒，365 天是上限不是目标。
• 密钥台账：把每个 key 的 expires_at 记进台账并监控到期时间。expires_at 为 null 的存量 key 在组织设 policy 之前不会自动过期——policy 落地后它们的行为会变，先盘点再等政策。
• 错误处理：传 0、负数、超过 31536000、超过 policy 上限、与 create_service_account_only=true 组合，都会被 schema 校验拒绝。捕获 400 类错误并把原因传给调用方，别让它变成深夜告警。
• 升级顺序：先升 SDK（Python ≥ v3.11.0 / Node ≥ v7.13.0）再动 key 策略——老版本类型里没有 policy 约束语义，校验错误信息会对不上。

6. 常见错误与排查

• 传 0 或负数：schema minimum: 1，直接被拒。要"立刻过期"不在这个参数的能力范围里——它是创建时设定，不是撤销工具。
• 超过 31536000：365 天是硬上限。"两年后再过期"的请求会被拒，分期轮换是正解。
• 与 create_service_account_only 同用：互斥。创建无初始 key 的服务账号时不传 expires_in_seconds。
• 误以为这是用户 key 的功能：截至 2026-09-10 核对，过期字段只在 Service Account 与 project API key 对象上；用户 API key 的类型层没有对应变化。
• policy 上限报错对不上文档：policy 上限是组织自设的，SDK 类型里看不到具体值，报错信息里的上限以你的组织配置为准——这也是"必须能在报错里读懂 policy"的原因。

7. 下一步

• 《openai-python 3.9 / 3.10 与 openai-node 7.11 / 7.12 更新解读：prompt cache 诊断、API key 过期与 GPT Image 2.5》：基础过期字段的首次落地（v3.10.0 / v7.11.0）与同批其他更新。
• 《gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读》：同一周 SDK 类型层的另一批重大变化。
• 《OpenAI API 错误处理与重试：401/429/5xx 实战模式》：schema 校验拒绝（400）与限流（429）的重试边界。
• 《Codex CI 集成实战：把 Codex CLI 跑进 GitHub Actions》：本文"CI key 30 天轮换"清单的完整落地场景。