Zendesk Developer Platform上に構築した場合、401または403エラーが発生する可能性があります。これらのステータスコードは、特にインテグレーションのライフサイクルの初期に見られる、開発者からのAPIリクエストの失敗の原因となっています。

どちらのエラーもアクセス制御に関連していますが、失敗の理由は異なり、必要なアプローチも異なります。これらを交換可能なものとして扱うと、時間を無駄にし、リクエストが繰り返し失敗してしまうことがあります。

この記事では、401エラーと403エラーがZendeskでどのように機能するか、迅速に診断する方法、そして自信を持って解決する方法について、実例とトラブルシューティングのステップを通して学習します。

学習内容

この記事をお読みいただくと、次のことがわかります。

  • Zendeskの401 Unauthorizedと403 Forbiddenの違い
  • How to authenticate correctly with API tokens, OAuth access tokens, and JWTs(APIトークン、OAuthアクセストークン、JWTを使用した正しい認証方法)
  • OAuthが認証に与える影響
  • How to Diagnostics of the Malformed Headers, incorrect subdomains, and expired credentials（不正なヘッダー、不正なサブドメイン、期限切れの資格情報の診断方法）

401と403の違い

どちらのステータスコードもアクセス制御に関連していますが、リクエストプロセスのさまざまな段階で失敗します。

401 権限がありません

401応答は、Zendesk APIがリクエストを認証できないことを意味します。Zendeskは発信者を特定できないため、権限やビジネスロジックは評価されません。

一般的な原因は次のとおりです。

  • Authorizationヘッダーがない、または形式が正しくない
  • 基本認証のBase64エンコーディングが正しくない
  • メールとトークンの形式が正しくありません
  • 期限切れまたは取り消されたAPIトークン
  • Basic認証ヘッダー内のOAuth
  • メッセージングのJWTが無効または期限切れです

401エラーが表示された場合は、リクエストが何をしようとしているかではなく、リクエストの認証方法に注目してください。

403 Forbidden

403応答は、Zendeskがリクエストを認証したが、認証されたIDに要求されたアクションを実行する権限がないことを意味します。

一般的な原因は次のとおりです。

  • 必要なスコープのないOAuthトークン
  • エージェント専用エンドポイントに対するエンドユーザーの資格情報
  • 別のブランドに属するリソースへのアクセス
  • アカウントのIP許可リストルール
  • 一時停止またはダウングレードされたエージェントアカウント

403エラーが表示された場合、認証は成功します。問題は認証です。

クイック診断フロー

アクセスに関する問題をデバッグする場合、最も迅速な方法は、問題を段階的に切り分けることです。

  1. カールテストから始めましょう。curlリクエストが失敗した場合、問題はアプリケーションコードではなく、資格情報またはアカウント設定に関連している可能性があります
  2. 正しいZendeskサブドメインを呼び出していることを確認します。資格情報は特定の環境を対象とし、サンドボックスと本番トークンは交換されません。
  3. 正しい認証方法を使用していることを確認してください。Basic Auth、OAuth、および JWT を混在させると、多くの場合に失敗します。
  4. 認証済みユーザーのロールを確認してください。多くのエンドポイントでは、認証に成功してもエージェントまたは管理者の権限が必要
  5. OAuthを使用する場合は、エンドポイントに必要なスコープがトークンに含まれていることを確認します。
  6. 最後に、リクエストの実行場所を検討します。APIトークンのBasic認証やその他のサポートされていないクライアント側フローを使用すると、Cross-Origin Resource Sharing（CORS）ポリシーが原因で、ブラウザからのリクエストが失敗することがよくあります。ブラウザからAPIを呼び出す必要がある場合は、CORSをサポートするOAuthを使用するか、バックエンドサービスを介してリクエストをルーティングするか、ZAFクライアントでZendeskアプリを使用します。CORSリクエストの詳細については、「Making client-side CORS requests to the Ticketing API（チケット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());

OAuthで401 Unauthorizedが発生する一般的な原因は、有効なアクセストークンが誤ったスキームで送信されたことです。この場合、Zendeskはリクエストを認証できず、スコープまたは権限を評価する前に401を返します。

OAuthトークンは、許可するアクションを定義するスコープも使用します。トークンは認証されますが、エンドポイントに必要なスコープがない場合、403 Forbiddenが返されます。

たとえば、tickets:readのトークンはチケットデータを取得できますが、チケットを作成または更新することはできません。適切なスコープなしで書き込みを試みると、常に403エラーが返されます。

403: You do not have access to this resource

この場合、認証は機能しますが、正しいスコープでトークンを再生成する必要があります。スコープの詳細については、「OAuth Tokens for Grant Types」を参照してください。

メッセージングのJWT認証

WebアプリやモバイルアプリでのZendeskメッセージングは、JWTを使用してエンドユーザーを特定します。バックエンドは、管理センターのシークレットを使用してJSON Webトークンに署名する必要があります。Zendeskは、メッセージングセッションをユーザーに関連付ける前にトークンを検証します。

メッセージングJWTには、Zendeskがユーザーの身元を解決できるように、特定のヘッダーとクレーム値が必要です。

メッセージングJWTには、少なくとも次のものが含まれている必要があります。

  • kid：ペイロードではなく、JWT ヘッダーの管理センターからのキー ID
  • external_id：ユーザーの一意のID
  • scope – メッセージングのエンドユーザー認証の値「user」

name、email、email_verifiedなどのオプションのクレームは、エージェントインターフェイスとSupportのメールベースのID照合にユーザーの詳細情報を入力できます。

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

メッセージング認証をデバッグするには、まず正しいシークレットと必要なクレームを確認します。認証は成功したが、IDの動作がオフであると思われる場合は、external_idおよびオプションのIDフィールドの安定した一貫した値をセッション全体で確認します。詳細については、「Authenticating users in your application（アプリケーションでのユーザーの認証）」を参照してください。

401エラーの一般的な原因

401応答は、Zendeskがリクエストを認証できず、発信者の身元を確認できないことを意味します。

Authorizationヘッダーの誤り、トークンの無効化、環境の不一致などが原因で、401応答のほとんどが返されます。

Basic認証ヘッダーを次のようにフォーマットします。

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

予期しない文字、空白、エンコーディングの問題により、サイレントエラーが発生することがよくあります。

Zendesk REST APIはブラウザ起点の認証をSupportしていません。CORS、セッションcookieの欠落、サポートされていない認証フローが原因で、クライアント側のJavaScriptリクエストが失敗します。代わりにバックエンドサービスまたはZAFクライアントを使用するZendeskアプリを使用してください。

403エラーの一般的な原因

403応答は、Zendeskがリクエストを認証したが、権限ルールがアクセスを拒否したことを示します。

OAuthの欠如は、ほとんどの403応答の原因となります。たとえば、tickets:readのトークンは、チケットの取得はできますが、作成や更新はできません。書き込みを試みると、必ず403エラーが返されます。

トークン作成後にOAuthコープを変更することはできません。スコープが間違っていた場合は、新しいトークンを生成します。

もう1つのよくある落とし穴は、エンドユーザーの資格情報を使用してエージェント専用のエンドポイントにコールすることです。エンドユーザーの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の制限に抵触する可能性があります。ブラウザの開発者コンソールを開き、エラーを確認します。401/403にAccess-Control-Allow-Originメッセージが表示された場合、ブラウザはZendeskがリクエストを処理する前にリクエストをブロックします。

3.未加工のリクエストヘッダーを調べる：

  • Authorizationヘッダーを記録します。アプリが送信する文字列をそのまま印刷します。非表示の空白文字がなく、BasicやBearerなどのプレフィックスが正しいことを確認します。
  • 環境の確認：アプリが正しいサブドメインを対象としていることを確認します。多くのチームは、本番環境の認証情報を含むサンドボックスURLをターゲットにしています。その逆も同様です。

4.スコープとクレームの確認：

  • OAuthの場合：/api/v2/OAuth/tokens/currentを呼び出して、現在のスコープをリストします。トークンにリソースに必要なスコープがあることを確認します。
  • メッセージング/JWTの場合：JWTペイロードを再検証します。子（キーID）がZendeskの設定と一致し、正しい署名シークレットを使用していることを確認します。

最終的な考察

Zendesk Developer Platformの401エラーと403エラーのほとんどは、予測可能な設定ミスによるものです。認証と承認を分離することで、診断をスピードアップし、信頼性を高めることができます。

資格情報を早期に検証し、スコープとロールを確認し、構造化された診断アプローチに従って問題を迅速に解決し、本番環境での繰り返しを防止します。

詳細については、APIトークンアクセス、OAuth認証、Zendesk App Framework、およびメッセージングJWT認証に関するZendeskのドキュメントを参照してください。

翻訳に関する免責事項：この記事は、お客様の利便性のために自動翻訳ソフ トウェアによって翻訳されたものです。Zendeskでは、翻訳の正確さを期すために相応の努力を払っておりますが、翻訳の正確性につ いては保証いたしません。

翻訳された記事の内容の正確性に関して疑問が生じた場合は、正式版である英語の記事 を参照してください。

Powered by Zendesk