Zendesk API認証とスコープ：完全な2026年ガイド

Zendeskとの連携機能を構築する場合、認証は最初のハードルです。間違えると、原因不明の403エラーのデバッグに何時間も費やすことになります。正しく行うと、安全で保守可能な接続が実現し、問題なく動作します。

このガイドでは、2026年のZendesk API認証について知っておくべきことをすべて網羅しています。さまざまな認証方法について説明し、OAuth（オーオース）のスコープの仕組みを解説し、実際に動作するコード例を用いて実装方法を正確に示します。

eesel AIでは、日々Zendeskとの連携機能を構築しています。何がうまくいき、何がうまくいかないのか、そして開発者をつまずかせる一般的な落とし穴を回避する方法を見てきました。

Zendesk API認証方式の理解

ZendeskはAPIリクエストを認証する方法を3つ提供していますが、そのうち1つは段階的に廃止されています。オプションを分解してみましょう。

3つの認証オプション

方法	最適な用途	セキュリティレベル	設定の容易さ
APIトークン	内部スクリプト、シングルユーザーアプリ	中	簡単
OAuthアクセストークン	マルチユーザーアプリ、サードパーティ連携	高	普通
パスワード（Basic認証）	レガシーシステムのみ	低	簡単

パスワード認証は非推奨であり、ZendeskはAPIトークンまたはOAuthへの移行を推奨しています。新たに始める場合は、パスワードを完全にスキップしてください。

APIトークン認証

APIトークンは最もシンプルなオプションです。これらは、Zendesk管理センターで作成する自動生成されたパスワードです。

認証情報の仕組みは次のとおりです。

{email_address}/token:{api_token}

例：

jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

この文字列をBase64エンコードすると、Authorizationヘッダーは次のようになります。

Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

またはcurlを使用する場合：

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

知っておくべき主な制限事項：

• アクティブなトークンは最大256個まで（すでに256個を超えている場合は2048個）
• トークンは、管理者を含むアカウント内の任意のユーザーになりすますことができます
• きめ細かい権限はありません：トークンは、それを作成したユーザーと同じアクセス権を持ちます
• トークンは、手動で取り消さない限り期限切れになりません

出典：Zendeskのセキュリティと認証に関するドキュメント

OAuthアクセストークン認証

OAuthは、ほとんどの連携機能にとってより良い選択肢です。スコープを通じて権限をきめ細かく制御でき、トークンは広範なアカウントアクセスを持つのではなく、特定のユーザーに紐付けられます。

フローは次のようになります。

1. アプリは、アクセスを承認するためにユーザーをZendeskにリダイレクトします
2. ユーザーは権限を付与し、Zendeskは認証コードをアプリに送信します
3. アプリはコードをアクセストークンと交換します
4. APIリクエストでBearer（ベアラー）トークンを使用します

リクエストは次のようになります。

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

OAuthは、APIトークンがCORS（Cross-Origin Resource Sharing）制限のために実行できないブラウザーからのクライアントサイドAPIリクエストもサポートしています。

出典：Zendesk OAuthヘルプドキュメント

OAuthスコープの説明

スコープはOAuthセキュリティの中心です。最小特権の原則に従い、アプリが実際に必要な権限のみを要求できます。

OAuthスコープとは？

スコープを権限証書と考えてください。Zendeskアカウントへのフルアクセスを取得する代わりに、特定の機能を要求します。レポートツールは、チケットへの読み取りアクセスのみを必要とする場合があります。同期ツールは、読み取りおよび書き込みアクセスを必要とします。管理ダッシュボードは、ユーザーに代わって行動するためのなりすまし権限を必要とする場合があります。

広範なスコープ

これらは、すべてのリソースへの一般的なアクセスを提供します。

• read: GETエンドポイントへのアクセスと、関連リソースのサイドローディング
• write: 作成、更新、および削除のためのPOST、PUT、およびDELETEエンドポイントへのアクセス
• impersonate: 管理者がエンドユーザーに代わってリクエストを行うことを許可します

リソース固有のスコープ

より細かく制御するために、権限を特定のリソースにスコープすることができます。

リソース	読み取りスコープ	書き込みスコープ
チケット	tickets:read	tickets:write
ユーザー	users:read	users:write
組織	organizations:read	organizations:write
ヘルプセンター	hc:read	hc:write
アプリ	apps:read	apps:write
トリガー	triggers:read	triggers:write
自動化	automations:read	automations:write
Webhook（ウェブフック）	webhooks:read	webhooks:write
マクロ	macros:read	macros:write
リクエスト	requests:read	requests:write
満足度評価	satisfaction_ratings:read	satisfaction_ratings:write
監査ログ	auditlogs:read	N/A（読み取り専用）

一部のリソースは書き込み専用です：any_channel:writeとweb_widget:write。

出典：Zendesk OAuthトークンAPIリファレンス

スコープ形式の違い（重要！）

開発者がつまずくことが多いのはここです。Zendeskは、使用するエンドポイントに応じて異なる形式を使用します。

OAuthトークンAPI（/api/v2/oauth/tokens）の場合：

{
  "token": {
    "client_id": 1234,
    "scopes": ["tickets:read", "users:read"]
  }
}

認証フロー（/oauth/tokens）の場合：

{
  "grant_type": "authorization_code",
  "scope": "tickets:read users:read"
}

最初は配列を使用します。2番目はスペースで区切られた文字列を使用します。これらを混同すると、紛らわしいエラーが発生します。

OAuth認証の実装

完全な実装をステップごとに見ていきましょう。

ステップ1：OAuthクライアントの作成

まず、アプリケーションをZendeskに登録する必要があります。

1. Zendesk管理センターで、アプリと連携機能 > API > OAuthクライアントに移動します

2. OAuthクライアントを追加をクリックします

3. 詳細を入力します。

   • 名前: アプリ名（ユーザーが承認時に表示します）
   • 説明: アプリの簡単な説明
   • クライアントの種類: モバイル/SPAアプリの場合はパブリック、サーバーサイドアプリの場合は機密を選択します
   • リダイレクトURL: コールバックURL（localhostを除き、HTTPSである必要があります）

4. 保存をクリックします

5. シークレットの値をすぐにコピーします。これは一度しか表示されません。

6. 一意の識別子（これはclient_idです）をメモします

クライアントの種類の理解：

• 機密クライアントは、認証情報を保護できる安全なサーバー上で実行されます。PKCE、クライアントシークレット、またはその両方を使用できます。
• パブリッククライアントは、認証情報が表示されるブラウザーまたはモバイルアプリで実行されます。セキュリティのためにPKCEを使用する必要があります。

サーバーサイドの連携機能を構築する場合は、機密を選択します。JavaScriptアプリまたはモバイルアプリの場合は、パブリックを選択します。

出典：Zendesk OAuthヘルプドキュメント

ステップ2：認証のリクエスト

ユーザーをZendeskの認証ページに送信します。

https://{subdomain}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  redirect_uri=https://yourapp.com/callback&
  client_id=your_unique_identifier&
  scope=read%20write&
  state=random_state_string

必須パラメーター：

• response_type=code（認証コードを返してほしい）
• redirect_uri（登録したものと一致する必要がある）
• client_id（一意の識別子）
• scope（スペースで区切られた権限のリスト）

オプションですが推奨：

• state（CSRF攻撃を防ぐためのランダムな文字列）
• code_challengeおよびcode_challenge_method=S256（PKCE用）

ユーザーには、アプリにアクセス権を付与するかどうかを尋ねる認証ページが表示されます。承認すると、Zendeskは認証コードを使用してredirect_uriにリダイレクトします。

https://yourapp.com/callback?code=7xqwtlf3rrdj8uyeb1yf

**重要：**認証コードは120秒で期限切れになります。速やかに交換してください。

ステップ3：アクセストークンのためのコードの交換

POSTリクエストを作成してコードを交換します。

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "7xqwtlf3rrdj8uyeb1yf",
    "client_id": "your_unique_identifier",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://yourapp.com/callback",
    "scope": "read write",
    "expires_in": 172800,
    "refresh_token_expires_in": 7776000
  }'

次のようなレスポンスが返されます。

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope": "read write",
  "expires_in": 172800,
  "refresh_token_expires_in": 7776000
}

両方のトークンを安全に保管してください。アクセストークンはAPI呼び出しに使用されます。リフレッシュトークンは、現在のトークンが期限切れになったときに新しいアクセストークンを取得します。

トークンの有効期限設定：

• expires_in: 300秒（5分）〜172,800秒（2日）
• refresh_token_expires_in: 604,800秒（7日）〜7,776,000秒（90日）

出典：Zendesk OAuthヘルプドキュメント

ステップ4：認証されたAPIリクエストの作成

アクセストークンを使用します。

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

またはPythonの場合：

import requests

headers = {
    "Authorization": f"Bearer {access_token}"
}
response = requests.get(
    "https://yourdomain.zendesk.com/api/v2/tickets.json",
    headers=headers
)

またはNode.jsの場合：

const axios = require('axios');

const response = await axios.get(
  'https://yourdomain.zendesk.com/api/v2/tickets.json',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`
    }
  }
);

アクセストークンが期限切れになったら、リフレッシュトークンを使用して、ユーザーに再認証を要求せずに新しいトークンを取得します。

ユースケース別の一般的なスコープ構成

連携機能が異なれば、必要な権限も異なります。一般的なシナリオの典型的なスコープ構成を次に示します。

読み取り専用のレポートツール

変更を加えることなくチケットデータをプルするダッシュボードの場合：

read

または、より具体的には：

tickets:read users:read organizations:read

これにより、ツールは何も変更せずにチケット、ユーザー、および組織を表示するためのアクセス権を取得します。

双方向同期連携

ZendeskをCRMまたは他のシステムと同期する場合：

tickets:read tickets:write users:read users:write organizations:read organizations:write

これにより、既存のデータを読み取り、更新をZendeskにプッシュバックできます。

ヘルプセンターのコンテンツ管理

ナレッジベースの記事を管理するツールの場合：

hc:read hc:write

これにより、権限がヘルプセンターのコンテンツのみにスコープされ、チケットとユーザーデータは範囲外に保持されます。

顧客向けのポータル

エンドユーザーが独自のチケットを作成および表示する埋め込みウィジェットの場合：

requests:read requests:write impersonate

impersonateスコープを使用すると、アプリはエンドユーザーがZendeskアカウントを必要とせずに、エンドユーザーに代わってチケットを作成できます。

認証エラーのトラブルシューティング

適切な設定でも、問題が発生することがあります。最も一般的な問題を修正する方法を次に示します。

403 Forbiddenエラー

403は、トークンは有効ですが、そのアクションに対する権限がないことを意味します。

原因：

• エンドポイントに必要なスコープがない
• スコープ形式が間違っている（配列と文字列）
• ユーザーロールがそのアクションを許可していない（エージェントが管理者専用のエンドポイントを使用しようとしているなど）

**修正：**エンドポイントに必要なスコープについては、APIドキュメントを確認してください。トークンを表示エンドポイントを使用して、トークンにそのスコープがあることを確認します。

401 Unauthorizedエラー

401は、トークンが無効、期限切れ、または不正であることを意味します。

原因：

• トークンが期限切れになった（有効期限を設定した場合）
• トークンがユーザーまたは管理者によって取り消された
• トークン形式が間違っている（たとえば、「Bearer」プレフィックスがない）

**修正：**リフレッシュトークンがある場合は、トークンをリフレッシュします。それ以外の場合は、ユーザーを再度認証フローにリダイレクトします。

一般的なOAuthエラー

エラー	意味	修正方法
invalid_grant	認証コードが期限切れになったか、すでに使用されている	新しい認証コードを取得します（120秒で期限切れになります）
redirect_uri_mismatch	リダイレクトURLが登録されたURLと一致しない	プロトコルと末尾のスラッシュを含む完全一致を確認します
invalid_scope	要求されたスコープが存在しない	スコープ名のスペルと形式を確認します
invalid_client	クライアントIDまたはシークレットが間違っている	管理センターからの認証情報を確認します

出典：Zendesk OAuthヘルプドキュメント

Zendesk API認証のセキュリティに関するベストプラクティス

認証を機能させることは最初のステップです。それを安全に保つことは継続的です。

トークン管理

• トークンを暗号化して保存する: トークンをプレーンテキストで保存したり、コードリポジトリにコミットしたりしないでください
• 自動ローテーションの実装: サービスの中断を避けるために、有効期限が切れる前にトークンをリフレッシュします
• 未使用のトークンを削除する: 使用しなくなった連携機能のトークンを取り消します
• トークンの使用状況を監視する: Zendeskはトークンがいつ使用されたかを追跡します。予期しないアクティビティに注意してください

スコープの選択

• 最小限のスコープを要求する: アプリが実際に必要な権限のみを要求します
• 付与された権限を確認する: トークンが持つスコープを定期的に監査します
• スコープ要件の文書化: コンプライアンスのために、各スコープが必要な理由の記録を保持します

連携機能のセキュリティ

• すべてのリクエストにHTTPSを使用する: Zendesk APIはSSL専用であり、TLS 1.2が必要です
• パブリッククライアントにPKCEを実装する: モバイルおよびブラウザーベースのアプリに必須
• 状態パラメーターの検証: CSRF攻撃を防ぐために、送信した状態パラメーターが一致することを常に確認します
• SNIのサポート: HTTPクライアントは、Server Name Indication TLS拡張機能をサポートする必要があります

出典：Zendeskのセキュリティと認証に関するドキュメント

eesel AIを使用した安全なZendesk連携の構築

これらすべてを管理するのは大変だと感じたら、それはあなただけではありません。認証は、Zendesk連携の構築において最もエラーが発生しやすい部分の1つです。

eesel AIでは、Zendesk OAuthを安全に処理するため、トークン管理、スコープ構成、またはリフレッシュロジックについて心配する必要はありません。当社のZendesk連携には、最小特権の原則に従う事前構成されたスコープ、自動トークンリフレッシュ、および一般的な認証問題に対する組み込みのエラー処理が付属しています。

また、Zendeskデータと連携してサポートワークフローを自動化できるAIエージェントも提供しています。これは、自動化に必要なものだけに制限されたスコープで、同じ安全なOAuthフローを介して接続します。

自分で構築する場合でも、当社のようなプラットフォームを使用する場合でも、重要なのは最初から認証を正しく行うことです。安全な基盤により、他のすべてが簡単になります。

自分で構築する場合でも、当社のようなプラットフォームを使用する場合でも、重要なのは最初から認証を正しく行うことです。安全な基盤により、他のすべてが簡単になります。