Zendesk による API トークン認証の廃止予告について - 影響範囲の調べ方と OAuth 移行を試してみた
はじめに
Zendesk が、API リクエストの認証方法としての API トークンを廃止します。
2027 年 4 月 30 日にすべての API トークンが恒久的に無効化されます。 影響を受けるのは Support API トークンだけで、メッセージングや Chat のトークンは対象外です。
2026 年 7 月 28 日から 30 日使われなかったトークンが自動的に非アクティブになり、2026 年 10 月 27 日以降は新しい API トークンを作れなくなります。月次バッチのように実行間隔が長いインテグレーションは、最終期限を待たずに止まります。
移行先は OAuth です。Webhook の一部については、OAuth よりアクションフローへの移行のほうが簡単な場合があると案内されています。
この記事では、自社が影響を受けるか調べる方法と、実際に OAuth へ移行して API を叩いた検証結果を紹介します。
対象読者
- Zendesk の API トークンを使ったインテグレーションを運用している方
- Zendesk の管理者で、自社が影響を受けるかを判断したい方
検証環境
- Zendesk の検証用インスタンス
- OAuth クライアントの種類: Confidential
- グラント: クライアントクレデンシャル
- API の呼び出し: curl
- 検証日: 2026 年 8 月 19 日
参考
- API リクエストの認証方法としての API トークンの提供終了に関するお知らせ (公式アナウンス、日本語)
- Announcing the removal of API tokens as an authentication method for API requests (同、英語)
- Migrating from API tokens to OAuth access tokens (開発者ドキュメント)
背景: 廃止のスケジュール
公式ドキュメントでは、廃止は以下 3 段階で行われると案内されています。
| 日付 | 起きること |
|---|---|
| 2026-07-28 | 30 日以上使われていないトークンを一括で非アクティブ化。以降も 30 日未使用で自動的に非アクティブ化され、非アクティブのまま 60 日で完全に削除される。この日以降に作成されたアカウントは API トークンを作成も使用もできない |
| 2026-10-27 | 既存のアカウントも、管理画面と API の両方から新しい API トークンを作成できなくなる。既存のアクティブなトークンは 2027 年 4 月 30 日まで使える |
| 2027-04-30 | 残っているすべてのトークンが恒久的に無効化される。再度アクティブにすることはできない。API トークンの管理ページも管理センターから削除される |
対象となる API として、チケット管理 API、ヘルプセンター API、音声 API が挙げられています。移行が間に合わない場合に動かなくなるものとして、自身の Zendesk アカウントへコールバックする Webhook、自動化やデータ同期のカスタムスクリプト、外部の開発者が作ったサードパーティインテグレーション、エージェントが Zendesk の画面を直接操作しないミドルウェアのワークフローが挙げられています。
影響有無の調査
管理センターで「アプリおよびインテグレーション > API > APIトークン」を開きます。廃止の告知バナーと、登録済みトークンの一覧が表示されます。
一覧の列は「ID」「説明」「作成者」「作成日時」「最終使用日時」「非アクティブになる日」「ステータス」です。見るべきは「非アクティブになる日」です。ここに日付が入っている場合、そのトークンは何もしなければその日に使えなくなります。
検証: OAuth への移行
ここからは、実際に OAuth へ移行する手順です。ユーザーの承認を挟まないサーバー間連携を想定し、クライアントクレデンシャルフローを使います。
OAuth クライアントを作成する
管理センターで「アプリおよびインテグレーション > API > OAuthクライアント」を開き、「OAuthクライアントを追加」を選びます。
クライアントの種類では Public と Confidential のどちらかを選びます。モバイルアプリや Web アプリのように認証情報を安全に保存できない環境で動くものが Public です。この場合は PKCE の使用が必須になります。安全に保存できるサーバー上で動くものが Confidential です。クライアントクレデンシャルフローを使えるのは Confidential だけなので、今回は Confidential を選びました。
「スコープ」の欄では、このクライアントが要求できる権限の上限を指定します。空欄にすると任意のスコープを要求できてしまうため、必要なものだけを選びます。今回は tickets:read、tickets:write、users:read の 3 つにしました。
保存するとシークレットが発行されます。あとから見返すことはできません。 その場で控えておいてください。控え損ねた場合は、編集画面の「再生成」で作り直せます。
アクセストークンを取得する
クライアント ID とシークレットを /oauth/tokens に送ります。
curl -X POST "https://{subdomain}.zendesk.com/oauth/tokens" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id={クライアントID}" \
--data-urlencode "client_secret={シークレット}" \
--data-urlencode "scope=tickets:read users:read"
応答は次のとおりでした。
{
"access_token": "eyJraWQi...",
"token_type": "bearer",
"expires_in": 1800,
"scope": "tickets:read users:read"
}
expires_in は 1800 秒、つまり 30 分です。クライアントクレデンシャルフローではリフレッシュトークンが返りません。 期限が切れたら同じリクエストをもう一度実行してトークンを取り直します。
API リクエストを書き換える
認証部分だけが変わります。
# 移行前: API トークンによる Basic 認証
curl "https://{subdomain}.zendesk.com/api/v2/tickets.json" \
-u "{メールアドレス}/token:{APIトークン}"
# 移行後: OAuth アクセストークン
curl "https://{subdomain}.zendesk.com/api/v2/tickets.json" \
-H "Authorization: Bearer {アクセストークン}"
どちらも HTTP 200 で同じチケットを取得できました。書き換えるのは認証ヘッダーだけで、エンドポイントもレスポンスの形式も変わりません。
スコープが足りないとどうなるか
tickets:read だけのトークンでチケットを作成しようとすると、HTTP 403 と次の応答が返りました。
{"error":"Forbidden","description":"You are missing the following required scopes: tickets:write, write"}
不足しているスコープ名が応答に含まれます。 呼び出しているエンドポイントを事前にすべて洗い出さなくても、実行しながら必要なスコープを足していけます。
一方、OAuth クライアントに設定したスコープの上限を超える要求をすると、トークンの取得段階で HTTP 400 になります。
{"error":"invalid_scope","error_description":"The requested scope is invalid, unknown, malformed, or exceeds the previously granted scope."}
organizations:read はスコープ一覧に存在する有効なスコープですが、このクライアントの上限に含めていないため拒否され、トークンは発行されませんでした。
403 と 400 のどちらが返るかで、直す場所が変わります。403 ならトークン要求時の scope の指定を、400 なら管理センターのクライアント設定を見直します。
誰として実行されているのかを確かめる
取得したトークンで GET /api/v2/users/me.json を呼びました。
{
"id": 11950397250831,
"name": "検証用の管理者",
"role": "admin"
}
このリクエストではユーザーの資格情報を一切送っていません。送ったのはクライアント ID とシークレットだけです。それでも、OAuth クライアントを作成した管理者として扱われました。
実際にチケットを作成すると、requester_id と submitter_id にも同じ ID が入りました。
{
"id": 2400,
"requester_id": 11950397250831,
"submitter_id": 11950397250831,
"via": { "channel": "api" }
}
まとめ
Zendesk の API トークンは 2027 年 4 月 30 日に完全に停止します。移行そのものは、認証ヘッダーを書き換えるだけなら難しくありません。むしろ、実行者が変わることと、トークンの取り直しをどこに実装するかを先に決めておくことが大事だと思います。なお、本記事の内容は 2026 年 8 月 19 日時点の公式ドキュメントと検証環境での確認にもとづいています。
