解决苹果Developer API的401 NOT_AUTHORIZED错误：JWT令牌过期时间详解

原创

于 2026-03-02 02:31:51 发布 · 1k 阅读

1. 从一次深夜报警说起：401 NOT_AUTHORIZED 到底是个什么鬼？

那天晚上，我正睡得迷迷糊糊，手机突然跟催命符一样响个不停。抓起来一看，监控告警，我们对接苹果 App Store Connect API 的服务挂了，错误信息就是那个让人血压飙升的 401 NOT_AUTHORIZED。点开日志一看，熟悉的配方，熟悉的味道：

{
  "errors": [{
    "status": "401",
    "code": "NOT_AUTHORIZED",
    "title": "Authentication credentials are missing or invalid.",
    "detail": "Provide a properly configured and signed bearer token, and make sure that it has not expired. Learn more about Generating Tokens for API Requests https://developer.apple.com/go/?id=api-generating-tokens"
  }]
}

“认证凭证缺失或无效”——这句话简直就像一句正确的废话。我们的密钥文件没动过，Issuer ID 和 Key ID 都对，代码也跑了好几个月了，怎么突然就“无效”了？相信很多第一次接触苹果 Developer API 的开发者，看到这个错误都会一头雾水，然后开始漫无目的地检查各种配置。其实，这个错误的罪魁祸首，十有八九就藏在那个不起眼的 exp 字段里，也就是 JWT 令牌的过期时间。苹果在这件事上，规矩特别严，而且跟很多其他云服务商（比如 AWS、Google Cloud）的惯例不太一样，一不小心就会踩坑。

简单来说，苹果要求你用 JWT（JSON Web Token）来证明你是你。这个令牌就像一张临时通行证，你得自己用私钥签发。通行证上必须写明签发人（iss）、有效期（exp）和观众（aud）。问题就出在这个有效期上。很多开发者，包括最初的我，会想当然地设置一个很长的有效期，比如 24 小时甚至 7 天，觉得这样省事，不用频繁生成。但苹果的安检人员（也就是他们的 API 网关）只认一个死理：你这张通行证的有效期，从签发那一刻算起，绝对不能超过 20 分钟。超出一秒，直接给你打上“无效”的标签，返回 401。所以，这篇文章我们就来把这个“20分钟”的来龙去脉、背后的原理、以及如何正确生成令牌，掰开揉碎了讲清楚，让你彻底告别这个烦人的 401 错误。

2. 深入原理：为什么苹果对 JWT 过期时间如此苛刻？

要理解这个限制，我们得先搞明白 JWT 在苹果 API 体系里扮演的角色。它不是一个普通的 API Key，而是一个基于密码学的、自包含的声明。你用自己生成的私钥（.p8文件）对它进行签名，苹果那边用对应的公钥来验证签名。验证通过，就相信令牌里的声明（比如你是谁、令牌何时过期）是真实有效的。这种机制的好处是，服务器端（苹果）无需维护一个令牌数据库来查询状态，验证过程是无状态的、高效的。

那么，为什么是 20 分钟，而不是 1 小时或者 1 天呢？这背后主要是安全考量。缩短令牌的生命周期，是减少令牌泄露后可能造成损害的最有效手段之一，这在安全领域被称为“最小权限原则”和“短期有效原则”。想象一下，如果你的令牌有效期是 24 小时，一旦不小心在日志中泄露或者被恶意软件窃取，攻击者就有充足的时间去滥用你的 API 权限，比如恶意创建证书、下架你的应用、甚至修改财务信息。而把有效期压缩到 20 分钟，就极大地缩小了这个攻击窗口。即使令牌不幸泄露，它很快也会自动失效，像一颗过了保质期的糖丸，对攻击者来说就没用了。

另外，这也和苹果 API 的设计哲学有关。App Store Connect API 主要用于自动化构建、测试、发布和报告查询等后台任务，这些操作通常是高频、短时、脚本化的。它不像一个用户登录会话，需要维持几个小时。因此，为每次或每批 API 调用生成一个短期有效的令牌，是更合理、更安全的模式。这个 20 分钟的限制，被明确写在了官方的令牌生成指南中，是铁律，不是建议。你可能会在其他地方看到 OAuth 2.0 的访问令牌（Access Token）有好几个小时的寿命，但请务必区分开，苹果的 JWT 是用于服务器到服务器的认证，规则完全不同。

2.1 JWT 令牌的结构解剖：关键字段一个都不能错

光知道 20 分钟还不够，我们得亲手拆解一个合格的 JWT，看看它到底由哪些部分组成。一个发给苹果 API 的 JWT 通常包含三部分：头部（Header）、载荷（Payload）和签名（Signature）。我们主要关注前两部分的内容。

头部（Header） 很简单，主要声明签名算法和密钥 ID：

{
  "alg": "ES256",
  "kid": "你的密钥ID，形如 ABCDEF1234",
  "typ": "JWT"
}

alg：必须是 ES256。这是椭圆曲线数字签名算法 (ECDSA) 使用 P-256 曲线和 SHA-256 哈希算法。苹果只支持这一种，别用 RS256 或者 HS256。
kid：你在苹果开发者后台创建私钥时获得的 Key ID。它告诉苹果用哪一把公钥来验证你的签名。
typ：固定为 "JWT"。

载荷（Payload） 是核心，包含了我们的声明：

标签