如果您在 Zendesk 开发者平台上构建，可能有时会遇到 401 或 403 错误。在开发者提交的失败 API 请求中，这两种状态代码占很大比例，尤其是在整合生命周期的早期。

尽管这两个错误都与访问控制有关，但它们失败的原因却大不相同，需要不同的调试方法。如果将它们视为可互换的，通常会导致时间浪费，并导致请求重复失败。

在这篇文章中，我们将通过实际示例和故障排除步骤，了解 401 和 403 错误在 Zendesk 上的工作方式、如何快速诊断以及如何放心解决。

您将学到什么

读完这篇文章后，您将了解：

  • Zendesk 上的 401 未授权和 403 禁止的区别
  • 如何使用 API 密钥、 OAuth访问密钥和 JWT 正确进行身份验证
  • OAuth范围如何影响授权
  • 如何诊断格式错误的标头、不正确的子域名和过期的凭证

 

了解 401 与 403

虽然这两个状态代码都与访问控制有关，但它们在请求处理的不同阶段失败。

401 未授权

401 响应表示 Zendesk API 无法对请求进行身份验证。Zendesk 无法确定来电人，因此不会尝试评估权限或业务逻辑。

常见原因包括：

  • 授权标头缺失或格式错误
  • 基本身份验证的 Base64 编码不正确
  • 电邮和密钥格式不正确
  • API 密钥已过期或已撤销
  • 在 Basic Auth 标头中使用OAuth密钥
  • 用于消息传送的 JWT 无效或已过期

如果收到 401 错误，请首先关注请求的身份验证方式，而不是请求的意图。

403 Forbidden

403 响应表示请求已成功通过身份验证，但已通过身份验证的身份没有执行请求操作的权限。

典型原因包括：

  • OAuth密钥缺失必需的作用域
  • 使用终端用户凭证呼叫仅供专员使用的端点
  • 尝试访问属于另一个品牌的资源
  • 帐户已启用 IP 限制
  • 被阻止或降级的专员帐户

如果收到 403 错误，则身份验证工作正常。问题出在授权上。

 

快速诊断流程

调试访问问题时，最快的办法就是逐步隔离问题。

首先使用 curl 测试您的请求。如果 curl 请求失败，问题可能出在凭证或帐户配置上，而不是您的应用程序代码上。

接下来，确认您调用的是正确的 Zendesk 子域名。凭证的作用域仅限于特定环境，沙盒环境和生产密钥不可互换。

然后，验证您是否使用了正确的身份验证方法。混合使用基本身份验证、 OAuth和 JWT 身份验证是一个常见的失败来源。

检查已通过身份验证的用户的用户角色。许多端点需要专员或管理员权限，即使身份验证成功也是如此。

如果您使用的是OAuth，请确认该密钥包含端点所需的范围。

最后，请考虑请求运行的位置。在使用 API 密钥基本身份验证或其他不受支持的客户端工作流程时，来自浏览器的请求通常会被跨浏览器资源共享 (CORS) 策略阻止。如果您需要从浏览器调用 API，请使用支持 CORS 的OAuth工作流程，或使用ZAF客户端通过后端服务或 Zendesk 应用转接请求。有关 CORS 请求的更多信息，请参阅 向工单处理 API 发出客户端 CORS 请求。 

 

身份验证正确

身份验证在任何权限或业务逻辑检查之前进行。如果身份验证失败，Zendesk 无法将请求与用户或整合关联起来，并返回 401 错误。

Zendesk 支持多种身份验证方法，每种方法都有严格的格式要求。

API 密钥身份验证

API 密钥使用基本身份验证，其中用户名包含 /token 后缀。

正确的格式是：

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

导致 401 错误的一个常见错误是省略 /token 后缀：

emailAddress:APITOKEN

在 Node.js 中，一个有效的示例如下所示：

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

 

OAuth 身份验证

OAuth访问密钥通常用于需要长期凭证或细化权限控制的整合。OAuth密钥必须使用 不记名身份 验证方案发送。正确的标头格式是：

Authorization: Bearer ACCESS_TOKEN

使用 curl 的示例请求：

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

在 Node.js 中，一个有效的示例如下所示：

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

使用OAuth时出现 401 未授权 错误的一个常见原因是使用错误的身份验证方案发送了有效的访问密钥。在这种情况下，Zendesk 无法对请求进行身份验证，并在评估范围或权限之前返回 401。

OAuth密钥还引入了 范围的概念，它明确定义了允许该密钥执行的操作。如果密钥缺少被调用端点所需的范围，它可能会成功进行身份验证，但仍返回 403 Forbidden 响应。

例如，带有 tickets:read 的 密钥可以抓取工单数据，但不能创建或更新工单。在没有适当作用域的情况下尝试写入操作将始终导致 403 错误。 

403: You do not have access to this resource

如果发生这种情况，身份验证将按预期工作，但必须使用正确的作用域重新生成密钥。有关范围的更多信息，请参阅 用于授予类型的OAuth密钥。

 

消息传送的 JWT 身份验证

在网络或移动应用程序中实施 Zendesk 消息传送时，JWT 身份验证用于安全地识别终端用户。在此模型中，您的后端负责使用在管理中心中配置的密钥生成并签署 JSON 网络密钥 (JWT)。Zendesk 会先验证密钥，然后再允许消息传送会话与用户关联。

与 API 密钥或OAuth不同，消息传送 JWT 需要特定的声明和标头信息，以便 Zendesk 正确解析用户身份。

消息传送 JWT 必须至少包括：

  • kid——Zendesk管理中心的密钥 ID。这必须包含在 JWT 标头中，而不是有效载荷中。
  • external_id—— 用户的唯一标识符。Zendesk 在匹配或创建用户记录时使用此值作为主键。
  • scope– 必须设置为“user”，表示密钥用于消息传送中的终端用户身份验证。

其他声明（例如 name、email和 email_verified 是可选的）可以包含在内，以填充专员界面中的用户详情，或支持基于电邮的身份匹配。


Node.js JWT 生成器示例： 

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
	keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

如果缺少必需的声明（例如 external_id 或 scope），或者使用错误的密钥对密钥进行签名，Zendesk 将返回 401 Unauthorized 响应。


导致 JWT 相关 401 错误的常见原因包括：

  • 使用来自错误环境（沙盒环境与生产环境）的 JWT 密钥
  • 发送过期的密钥或带有基于无效时间的声明的密钥
  • 省略必要声明，例如 external_id 或 scope 
  • 使用不正确或轮换的密钥对密钥进行签名
  • 发送格式错误或编码不正确的 JWT

在调试消息传送身份验证问题时，首先确认密钥是否使用正确的密钥签名，并包含所需的声明。如果身份验证成功，但用户身份行为异常，请检查用于 external_id 和任何可选身份字段的值，确保其在各个会话中稳定一致。有关更多信息，请参阅 在您的应用程序中对用户进行身份验证。
 

401 错误的常见原因

401 响应表示 Zendesk 无法对请求进行身份验证，也无法确定来电人的身份。

这通常是由于授权标头结构错误、密钥禁用或环境不匹配造成的。

基本身份验证标头的格式必须如下或同等格式：

headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
}

意外字符、空格或编码问题经常导致静默失败。

最后，请记住，Zendesk REST API 不支持浏览器来源身份验证。客户端 JavaScript 请求将由于 CORS、会话 Cookie 缺失和不受支持的身份验证流程而失败。请改用后端服务或使用ZAF客户端构建的 Zendesk 应用。

 

403 错误的常见原因

403 响应表示 Zendesk 已对请求进行身份验证，但由于权限规则而拒绝访问。

最常见的原因是缺少OAuth范围。例如，带有 ticket:read 的密钥可以抓取工单，但不能创建或更新工单。写入尝试始终会返回 403 错误。

OAuth范围在密钥创建后无法修改。如果作用域不正确，则必须生成新的密钥。

另一个容易造成混淆的来源是尝试使用终端用户凭证呼叫仅限专员使用的端点。终端用户OAuth密钥可能适用于 /users/me，但在调用受限端点（如工单、视图或工单字段）时将返回 403。

其他常见原因包括密钥已撤销、IP 允许列表限制，以及多品牌访问限制。在这些情况下，请求将被拒绝，原因可能是凭证不再活跃，或用户不满足特定访问标准。

 

逐步故障排除方法

1.单独验证凭证 如有疑问，请先从等式中删除应用程序代码。使用 curl 验证您的凭证：

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"
  • 如果失败：此问题可能是凭证或帐户相关的问题。
  • 如果操作成功：凭证有效。问题出在您的应用程序逻辑或环境中。转到步骤 2。

2.检查 CORS 限制：如果 curl 命令有效，但您的客户端应用程序失败，则您可能遇到了 CORS 限制。

打开浏览器的开发者控制台并检查错误。如果您看到 401/403 错误，并伴有一条关于 Access-Control-Allow-Author 的控制台消息，则表示浏览器在 Zendesk 无法处理请求之前阻止了该请求。

3.检查原始请求标头 如果您在运行服务器端代码（ Node.js、Python、 PHP 等）时仍然遇到问题：。

  • 记录 Authorization 标头：打印您的应用程序发送的确切字符串。确保没有隐藏的空白字符或不正确的前缀（例如，确保正确使用 Basic 和不记名）。
  • 验证环境：确认您的应用程序针对的是正确的子域名。生产凭证不小心指向沙盒环境 URL 是很常见的，反之亦然。

1.验证范围和声明 如果身份验证成功，但您收到了 403 Forbidden，则您的密钥可能缺乏必要的权限。

  • 对于OAuth：调用 /api/v2/oauth/tokens/current 端点以验证您当前的作用域。确保密钥具有您要访问的资源所需的范围。

  • 对于消息传送/JWT：重新验证您的 JWT 有效载荷。确保子密钥（密钥 ID）匹配您的 Zendesk 配置，并且用于生成密钥的签名密钥正确。

     

最后的想法

Zendesk 开发者平台上的大多数 401 和 403 错误都源自少数可预测的配置错误。明确区分身份验证失败和授权失败后，调试将显着提高速度和可靠性。

通过尽早验证凭证、确认范围和用户角色，并遵循结构化诊断方法，您可以快速解决这些问题，并防止其在生产环境中再次出现。

有关更多详情，请参阅 Zendesk 文档：API 密钥访问、OAuth身份验证、Zendesk 应用框架和 消息传送 JWT 身份验证。

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。

由 Zendesk 提供技术支持