如果您在 Zendesk 开发者平台上进行开发，可能会遇到 401 或 403 错误。我们发现许多开发者 API 请求失败的原因就是这些状态代码，尤其是在整合生命周期的早期。

尽管这两个错误都与访问控制有关，但它们失败的原因不同，需要不同的解决方法。如果您将它们视为可互换的，您可能经常会浪费时间并产生重复的失败请求。

您将学到什么

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

  • Zendesk 中 401 未授权和 403 禁止错误的区别
  • 如何快速诊断错误
  • 如何使用 API 密钥、 OAuth访问密钥和 JWT（JSON 网络密钥）正确进行身份验证
  • OAuth范围如何影响授权
  • 如何诊断格式错误的标头、不正确的子域名和过期的凭证
  • 通过实际示例和故障排除步骤，如何自信地解决错误

401 和 403 错误的区别

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

401 - 未授权

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

常见原因包括：

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

如果您收到 401 错误，请关注请求的身份验证方式，而不是请求尝试执行的操作。

403 Forbidden

403 响应表示 Zendesk 已对请求进行身份验证，但已通过身份验证的身份缺乏执行请求操作的权限。

典型原因包括：

  • 没有必需范围的OAuth令牌
  • 针对仅限专员端点的终端用户凭证
  • 访问属于另一个品牌的资源
  • 帐户 IP 允许列表规则
  • 被阻止或降级的专员帐户

如果您收到 403 错误，则身份验证成功。问题出在授权上。

快速诊断流程

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

  1. 从 curl 测试开始。如果 curl 请求失败，问题可能涉及凭证或帐户配置，而不是您的应用程序代码
  2. 确认您调用的是正确的 Zendesk 子域名。凭证的范围仅限于特定环境，沙盒环境和生产令牌不能互换。
  3. 检查您是否使用了正确的身份验证方法。混淆基本身份验证、 OAuth和 JWT 通常会导致失败。
  4. 检查已通过身份验证的用户的角色。许多端点需要专员或管理员权限，即使身份验证成功也是如此
  5. 如果您使用OAuth，请确认令牌包含端点所需的范围
  6. 最后，请考虑请求的运行位置。当您使用 API 令牌基本身份验证或其他不受支持的客户端工作流程时，由于跨源资源共享 (CORS) 政策，浏览器源请求通常会失败。如果您必须从浏览器调用 API，请使用支持 CORS 的OAuth工作流程，通过后端服务路由请求，或结合使用 Zendesk 应用和ZAF客户端。有关 CORS 请求的更多信息，请参阅向工单处理 API 发出客户端 CORS 请求。

如何正确进行身份验证

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

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

API 密钥身份验证

API 令牌使用基本身份验证，用户名必须包含/token后缀。

正确的格式是：

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://yoursubdomain.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://yoursubdomain.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());

导致 401 Unauthorized with OAuth的常见原因是使用错误的方案发送了有效的访问令牌。在这种情况下，Zendesk 无法对请求进行身份验证，并在评估范围或权限之前返回 401。

OAuth令牌还使用范围来定义允许的操作。如果令牌缺少端点所需的作用域，则在进行身份验证时仍会返回403 Forbidden 。

例如，带有tickets:read 的令牌可以抓取工单数据，但无法创建或更新工单。没有正确作用域的写入尝试始终会返回 403 错误。

403: You do not have access to this resource

如果发生这种情况，身份验证可以工作，但您必须使用正确的作用域重新生成密钥。有关范围详情，请参阅授权类型的OAuth密钥。

如何使用 JWT 身份验证进行消息传送

网络或移动应用中的 Zendesk 消息传送使用 JWT 来识别终端用户。您的后端必须使用来自管理中心的密钥对 JSON 网络密钥进行签名。Zendesk 会先验证密钥，然后再将消息传送会话与用户关联。

消息传送 JWT 需要特定标头和声明值，以便 Zendesk 解析用户身份。

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

  • kid ：JWT 标头中管理中心的密钥 ID，而不是有效负载
  • external_id ：用户的唯一标识符
  • scope – 值“user”，用于消息传送中的终端用户身份验证

可选声明（例如name 、 email和email_verified）可在专员界面中填充用户详情，并Support基于电邮的身份匹配。

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（401 未经授权）。

JWT 常见 401 原因：

  • 来自错误环境（沙盒环境与生产环境）的 JWT 密钥
  • 令牌过期或基于时间的无效声明
  • 不存在必要声明（例如 external_id 或 scope）
  • 使用不正确或轮换的密钥签名的令牌
  • 格式错误或编码不正确的 JWT

要调试消息传送身份验证，请先确认正确的密钥和所需的声明。如果身份验证成功，但身份行为似乎关闭，请在各个会话中验证 external_id 以及任何可选身份字段的值是否稳定。有关更多信息，请参阅在应用程序中对用户进行身份验证。

401 错误的常见原因

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

大多数 401 响应是由不正确的授权标头、已禁用的令牌或环境不匹配引起的。

设置基本身份验证标头的格式，如下所示：

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

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

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

403 错误的常见原因

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

大多数 403 响应都是由于缺少OAuth范围造成的。例如，带有 tickets:read 的令牌可以抓取工单，但无法创建或更新工单。尝试写入始终返回 403 错误。

您无法在密钥创建后修改OAuth范围。如果范围错误，则生成新令牌。

另一个常见陷阱：使用终端用户凭证调用仅限专员的端点。终端用户OAuth令牌可调用/users/me ，但对于受限端点（例如工单、视图或工单字段），将返回 403。

其他原因包括令牌已撤销、IP 允许列表规则以及多品牌访问限制。在这些情况下，Zendesk 会因为凭证处于非活跃状态或用户不满足访问标准而拒绝请求。

逐步故障排除方法

1.单独验证凭证：

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

2.检查 CORS 限制：

如果 curl 可以正常工作，但您的客户端应用失败，则您可能遇到了 CORS 限制。打开浏览器开发者控制台并查看错误。如果您看到带有 Access-Control-Allow-Origin 消息的 401/403，则表示浏览器会在 Zendesk 处理之前阻止该请求。

3.检查原始请求标头：

  • 记录授权标头：打印您应用发送的确切字符串。确认没有隐藏的空格以及正确的前缀，例如 Basic 或不记名。
  • 验证环境：确认您的应用定位到正确的子域名。许多团队将生产凭证作为沙盒环境 URL 的目标，反之亦然。

4.验证范围和声明：

  • 对于OAuth：调用/api/v2/oauth/tokens/current以列出当前范围。确认令牌具有资源所需的范围。
  • 对于消息传送/JWT：重新验证您的 JWT 有效负载。确认该子密钥（密钥 ID）匹配您的 Zendesk 配置，并且您使用了正确的签名密钥。

最后的想法

Zendesk 开发者平台上的大多数 401 和 403 错误都来自少数可预测的错误配置。将身份验证与授权分开可以加快诊断速度并提高可靠性。

尽早验证您的凭证，确认范围和用户角色，并按照结构化诊断方法快速解决问题，避免在生产中重复出现此类问题。

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

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

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

由 Zendesk 提供技术支持