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

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

学習内容

この投稿を終えると、次のことがわかります。

  • Zendeskの401 Unauthorizedエラーと403 Forbiddenエラーの違い
  • エラーをすばやく診断する方法
  • APIトークン、OAuthアクセストークン、およびJWT(JSON Webトークン)を使用して正しく認証する方法
  • OAuthが認証に与える影響
  • 不正な形式のヘッダー、不正なサブドメイン、期限切れの資格情報の診断方法
  • 実践例とトラブルシューティング手順を通じて、自信を持ってエラーを修正する方法

401エラーと403エラーの違い

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

401 Unauthorized

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

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

  • 認証ヘッダーがない、または形式が正しくない
  • Basic認証の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認証やその他のサポートされていないクライアント側フローを使用すると、クロスオリジンリソース共有（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がユーザーのIDを解決できるように、特定のヘッダーとクレーム値が必要です。

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

  • kid：ペイロードではなく、JWT ヘッダーの管理センターからのキー ID
  • external_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または正しくエンコードされていないJWT

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

401エラーの一般的な原因

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

認証ヘッダーの誤り、無効なトークン、または環境の不一致により、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.rawリクエストヘッダーの検査：

  • 認証ヘッダーを記録します。アプリが送信する正確な文字列を出力します。非表示の空白文字がないことと、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