Zendesk API OAuth スコープ：完全な開発者ガイド

Zendeskとの連携を構築する際、アプリケーションが何を実行でき、何を実行できないかを制御することは非常に重要です。OAuth（オーオース）スコープは、アクセス許可のゲートとして機能し、アプリケーションがアクセスできるZendesk API（エーピーアイ）のどの部分を正確に指定できます。

Zendeskアカウント全体への広範なアクセスを許可するAPIトークンとは異なり、OAuthスコープを使用すると、最小特権の原則に従うことができます。必要な権限のみをリクエストし、それ以上はリクエストしません。これにより、連携がより安全になり、監査が容易になります。

このガイドでは、Zendesk API OAuthスコープについて知っておく必要のあるすべてのこと、つまり、それらが何であるか、どのスコープが利用可能か、それらを実装する方法、および連携を安全に保つためのベストプラクティスについて説明します。

Zendesk API OAuthスコープとは？

ZendeskのOAuthスコープは、APIリソースへのアクセスを制御するアクセス許可の宣言です。OAuthトークンを作成するときに、アプリケーションが実行できるアクション（チケットの読み取り、ユーザーレコードへの書き込み、ヘルプセンターコンテンツの管理など）を決定するスコープを指定します。

スコープを、建物内の特定の部屋への鍵と考えてください。すべてのドアを開けるマスターキー（APIトークンのようなもの）を持つ代わりに、入る必要のある部屋の鍵のみをリクエストします。連携でチケットデータを読み取る必要がある場合は、readまたはtickets:readスコープをリクエストします。ユーザーを削除したり、トリガーを変更したりするアクセス権は得られません。

この粒度の細かいアプローチは、いくつかの理由で重要です。

• セキュリティ（Security）: トークンが侵害された場合、損害はスコープされたアクセス許可に限定されます。
• コンプライアンス（Compliance）: アプリケーションがアクセスするデータを正確に示すことができます。
• ユーザーの信頼: エンドユーザーは、OAuth認証中に付与するアクセス許可を正確に確認できます。
• デバッグ（Debugging）: 何かが壊れた場合、どのアクセス許可が関係しているかを正確に把握できます。

Zendeskは、トークンの作成方法に応じて、2つの主要なスコープ形式をサポートしています。OAuth Tokens APIは配列形式（"scopes": ["read"]）を使用し、grant-type token endpointはスペース区切りの文字列（"scope": "read write"）を使用します。実装セクションでは、両方のアプローチについて説明します。OAuthとAPIトークンのより詳細な比較については、Zendeskの認証ガイドを参照してください。

Zendeskで利用可能なOAuthスコープ

Zendeskは、スコープを2つのカテゴリに整理します。リソース全体に適用される広範なスコープと、個々のAPIエンドポイントを対象とするリソース固有のスコープです。

広範なスコープ

これらの3つのスコープは、すべてのZendeskリソースへのアクセスを制御します。

スコープ（Scope）	アクセスレベル（Access Level）	最適な用途（Best For）
read	GETエンドポイントとサイドローディング	レポートツール、分析ダッシュボード、読み取り専用の連携
write	POST、PUT、DELETEエンドポイント	同期ツール、自動化プラットフォーム、双方向連携
impersonate	エンドユーザーに代わってのリクエスト	カスタマーポータル、埋め込みサポートウィジェット、プロキシアプリケーション

impersonateスコープは特筆に値します。これにより、管理者はエンドユーザーに代わってAPIリクエストを行うことができます。これは、管理者認証情報を公開せずに、チケットを作成したり、リクエスト履歴にアクセスしたりする必要がある顧客向けアプリケーションを構築する場合に役立ちます。このスコープには管理者権限が必要であり、慎重に使用する必要があります。

リソース固有のスコープ

より詳細な制御のために、Zendeskでは、構文resource:scopeを使用して、特定のスコープへのアクセス許可をスコープできます。スコープされたアクセスをサポートするリソースを次に示します。

リソース（Resource）	読み取りスコープ（Read Scope）	書き込みスコープ（Write Scope）	注（Notes）
tickets	tickets:read	tickets:write	コアチケッティング機能
users	users:read	users:write	ユーザー管理とプロファイル
organizations	organizations:read	organizations:write	組織レコード
auditlogs	auditlogs:read	N/A	設計上、読み取り専用
hc (ヘルプセンター)	hc:read	hc:write	記事、カテゴリ、セクション
apps	apps:read	apps:write	アプリマーケットプレイス管理
triggers	triggers:read	triggers:write	ビジネスルール自動化
automations	automations:read	automations:write	時間ベースの自動化
targets	targets:read	targets:write	通知ターゲット
webhooks	webhooks:read	webhooks:write	Webhook構成
macros	macros:read	macros:write	定型応答
requests	requests:read	requests:write	エンドユーザーチケットインターフェイス
satisfaction_ratings	satisfaction_ratings:read	satisfaction_ratings:write	CSATデータ
dynamic_content	dynamic_content:read	dynamic_content:write	動的コンテンツアイテム
any_channel	N/A	any_channel:write	書き込み専用
web_widget	N/A	web_widget:write	書き込み専用
zis	zis:read	zis:write	Zendesk Integration Services（Zendeskインテグレーションサービス）

ここでの柔軟性は強力です。スコープを組み合わせて、正確なアクセス許可セットを作成できます。たとえば、"scopes": ["tickets:read", "users:write", "organizations:read"]を使用すると、チケットと組織への読み取りアクセス権が付与され、ユーザーレコードを更新する機能が追加されます。

OAuthスコープの構文と形式

構文を正しく理解することが重要です。Zendeskは無効なスコープ形式でもトークンを返しますが、それらのトークンを使用したAPI呼び出しは「Forbidden（禁止）」エラーで失敗します。

非グラントタイプのトークン（スコープ配列）

OAuth Tokens APIを使用してトークンを直接作成する場合（通常は内部使用または管理者作成のトークン）、配列形式を使用します。

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

重要なポイント:

• パラメータ名はscopes（複数形）です。
• 値は文字列のJSON配列です。
• 各スコープは個別の配列要素です。
• エンドポイント：POST /api/v2/oauth/tokens

グラントタイプのトークン（スコープ文字列）

OAuth認証フロー（認証コード、リフレッシュトークン、またはクライアント認証情報）を実装する場合は、スペース区切りの文字列形式を使用します。

{
  "grant_type": "authorization_code",
  "code": "7xqwtlf3rrdj8uyeb1yf",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "tickets:read users:write"
}

重要なポイント:

• パラメータ名はscope（単数形）です。
• 値はスペース区切りの文字列です。
• 複数のスコープは同じ文字列に入ります。
• エンドポイント：POST /oauth/tokens

一般的なスコープの組み合わせ

一般的なユースケースの実用的なスコープの組み合わせを次に示します。

読み取り専用レポート:

"scopes": ["read"]

ユーザー検索によるチケット管理:

"scopes": ["tickets:read", "tickets:write", "users:read"]

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

"scopes": ["hc:read", "hc:write", "tickets:read"]

完全な管理者アクセス（控えめに使用）:

"scopes": ["read", "write"]

アプリケーションでOAuthスコープを実装する方法

OAuthクライアントの作成から、スコープされた最初のAPIリクエストの作成まで、完全な実装について説明します。

ステップ1：ZendeskでOAuthクライアントを作成する

スコープされたトークンをリクエストする前に、アプリケーションをZendeskでOAuthクライアントとして登録する必要があります。

1. 管理者としてZendeskアカウントにログインします。

2. 管理センター > アプリと連携 > API > OAuthクライアントに移動します。

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

4. 必須フィールドに入力します。

   • 名前: アプリケーション名（ユーザーは認証中にこれを確認します）。
   • 説明: アプリの簡単な説明。
   • クライアントの種類: モバイル/SPAアプリの場合はパブリック、サーバーサイドアプリの場合はコンフィデンシャルを選択します。
   • リダイレクトURL: コールバックURL（localhostを除き、HTTPSである必要があります）。

5. 保存をクリックします。

6. シークレット値をすぐにコピーします（完全に1回だけ表示されます）。

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

重要: クライアントの種類としてパブリックを選択した場合は、セキュリティのためにPKCE（Proof Key for Code Exchange）を実装する必要があります。コンフィデンシャルクライアントは、PKCE、クライアントシークレット、またはその両方を使用できます。

ステップ2：スコープを使用して認証をリクエストする

リクエストされたスコープを使用して、ユーザーをZendeskの認証エンドポイントに送信します。

https://{サブドメイン}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  redirect_uri=https://your-app.com/callback&
  client_id=your_unique_identifier&
  scope=read%20write&
  state=random_state_string

必須パラメータ:

• response_type=code: 認証コードが必要であることを示します。
• redirect_uri: ステップ1で登録されたURLのいずれかと一致する必要があります。
• client_id: OAuthクライアントの一意の識別子。
• scope: リクエストされたスコープのスペース区切りリスト。

推奨パラメータ:

• state: CSRF攻撃を防ぐためのランダムな文字列（ユーザーが戻ってきたときにこれが一致することを確認します）。
• code_challengeおよびcode_challenge_method=S256: パブリッククライアントでのPKCEに必要です。

ユーザーには、リクエストしているスコープを一覧表示する認証画面が表示されます。アクセスを承認または拒否します。

ステップ3：認証コードをアクセストークンと交換する

ユーザーが承認すると、Zendeskは認証コードを使用してコールバックURLにリダイレクトします。

https://your-app.com/callback?code=7xqwtlf3rrdj8uyeb1yf&state=random_state_string

このコードをアクセストークンと交換します。

curl https://{サブドメイン}.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://your-app.com/callback",
    "scope": "read write"
  }'

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

応答には、アクセストークンとリフレッシュトークンが含まれます。

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

ステップ4：APIリクエストでアクセストークンを使用する

APIリクエストにBearerトークンとしてトークンを含めます。

curl https://{サブドメイン}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

トークンは、スコープに一致するエンドポイントでのみ機能します。tickets:readスコープを持つトークンはチケットを取得できますが、作成することはできません（それにはtickets:writeが必要です）。

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

連携が異なれば、必要なアクセス許可セットも異なります。頻繁に見られる構成を次に示します。

レポートおよび分析ツール

これらのツールは、データの読み取りのみを必要とします。

"scope": "read"

または、より制限的：

"scope": "tickets:read users:read organizations:read"

双方向同期連携

同期ツールは、複数のリソースにわたって読み取りおよび書き込みを行う必要があります。

"scope": "tickets:read tickets:write users:read users:write organizations:read organizations:write"

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

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

"scope": "hc:read hc:write"

顧客向けポータル

アプリケーションがエンドユーザーに代わって動作する場合：

"scope": "requests:read requests:write impersonate"

自動化およびワークフローツール

ビジネスルールを管理するツールの場合：

"scope": "triggers:read triggers:write automations:read automations:write webhooks:read webhooks:write"

スコープ関連のエラーのトラブルシューティング

適切に実装しても、エラーが発生します。最も一般的なエラーの処理方法を次に示します。

「Forbidden（禁止）」エラー（403）

これは、最も一般的なスコープ関連のエラーです。これは、トークンにリクエストされたエンドポイントのアクセス許可がないことを意味します。

原因:

• エンドポイントに必要なスコープがない
• 無効なスコープ形式（配列と文字列の不一致）
• ユーザーの役割にアクセス許可がない（OAuthスコープはユーザーのアクセス許可によって制約されます）

解決策: Zendesk APIドキュメントでエンドポイントに必要なスコープを確認し、トークンにそれが含まれていることを確認します。一部のエンドポイントでは、OAuthスコープに関係なく管理者権限が必要になることに注意してください。トークンの作成と管理の詳細については、ZendeskのOAuthトークンチュートリアルを参照してください。

401 Unauthorized（認証されていません）

これは、期限切れまたは取り消されたトークンを示します。

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}

解決策: リフレッシュトークンを使用して新しいアクセストークンを取得するか、リフレッシュトークンも期限切れになっている場合は、ユーザーを再度認証フローに通してリダイレクトします。

無効なスコープ形式

スコープを間違った形式で渡した場合（文字列が予想される場合に配列、またはその逆）、Zendeskはトークンを発行する可能性がありますが、API呼び出しは失敗します。

解決策: 使用しているエンドポイントを再確認してください。

• /api/v2/oauth/tokensは"scopes": []配列形式を使用します。
• /oauth/tokensは"scope": ""文字列形式を使用します。

スコープと役割の不一致

OAuthスコープは、ユーザーの役割によってフィルタリングされます。エージェントのOAuthトークンは、トークンにwriteスコープがあっても、管理者専用のエンドポイントにアクセスできません。

解決策: アプリケーションを認証するユーザーに、連携の要件に必要な役割のアクセス許可があることを確認します。

OAuthスコープセキュリティのベストプラクティス

これらのプラクティスに従うことで、Zendesk連携を安全に保つことができます。

最小限のスコープをリクエストする

絶対に必要とするアクセス許可のみを要求します。連携でチケットを読み取るだけの場合は、writeスコープをリクエストしないでください。これにより、トークンが侵害された場合のエクスポージャーが制限されます。

可能な場合はコンフィデンシャルクライアントを使用する

サーバーサイドアプリケーションは、クライアントシークレットを持つコンフィデンシャルクライアントを使用する必要があります。パブリッククライアント（モバイルアプリ、SPA）は、PKCEを実装する必要があります。

トークンリフレッシュロジックを実装する

アクセストークンは期限切れになります。アプリケーションに自動リフレッシュロジックを組み込む必要があります。

response = requests.get(api_url, headers=headers)
if response.status_code == 401:
    new_token = refresh_access_token(refresh_token)
    headers['Authorization'] = f'Bearer {new_token}'
    response = requests.get(api_url, headers=headers)

トークンを安全に保存する

アクセストークンとリフレッシュトークンをパスワードのように扱います。暗号化して保存し、ログに記録したり、クライアントサイドコードで公開したりしないでください。

状態パラメータを検証する

CSRF攻撃を防ぐために、OAuthフローで常にstateパラメータを含めて検証します。

安全な連携プラットフォームの使用を検討する

OAuth連携を安全に構築するには、トークンの保存、リフレッシュロジック、およびエラー処理に注意を払う必要があります。カスタマーサポート連携を構築する場合は、適切なスコープ管理が組み込まれたeesel AIなどのプラットフォームの使用を検討してください。当社のAI Agentは、デフォルトで最小特権の原則に従い、必要な最小限のスコープを使用してZendeskと連携します。Zendeskのドキュメントで、OAuthトークンの表示と管理の詳細を確認することもできます。

結論

Zendesk API OAuthスコープを使用すると、連携がアクセスできるものを正確に制御できます。利用可能なスコープを理解し、正しく実装し、セキュリティのベストプラクティスに従うことで、強力で安全な連携を構築できます。

主なポイント：

• 単純な連携には広範なスコープ（read、write）を使用し、粒度の細かい制御にはリソース固有のスコープを使用します。
• スコープ形式をトークンエンドポイント（配列と文字列）に一致させます。
• 常に最小限のアクセス許可をリクエストします。
• リフレッシュロジックを使用して、トークンの有効期限切れを適切に処理します。
• ユーザーの役割はOAuthスコープを制約することを忘れないでください。

単純なレポートツールを構築する場合でも、複雑な双方向同期を構築する場合でも、適切なスコープ構成は安全なZendesk連携の基礎となります。