現在のプランを確認

すべてのSuiteプランで利用可能すべてのSupportプランで利用可能

ファストパス：管理センター >「アプリおよびインテグレーション」>「アプリ」>「Zendesk API」

OAuth 2を使用して、アプリケーションからZendeskへのすべてのAPIリクエストを承認することができます。OAuthは、アプリケーションがZendeskユーザーのパスワードのような秘密情報を保存および使用することなくZendeskのデータにアクセスするための安全な手段です。

OAuth認証を使用するには、アプリケーションをZendeskに登録する必要があります。また、OAuth認証フローをサポートするために、いくつかの機能をアプリケーションに追加する必要があります。

この記事では、次のトピックについて説明します。

  • アプリケーションをZendeskに登録する
  • OAuth認証フローをアプリケーションに実装する

関連記事：

  • OAuth認証フローを実装するWebアプリを開発するチュートリアルについては、「OAuth Webアプリの開発」を参照してください。
  • ZendeskアプリへのOAuth認証フローの実装方法については、「Adding third-party OAuth to a Support app」を参照してください。
  • アプリケーションによるアカウントへのアクセスをユーザーに許可してもらう必要がない場合でも、OAuthトークンを使用してAPIリクエストを認証できます。「Creating and using OAuth tokens with the API（APIを使用したOAuthトークンの作成と使用）」を参照してください。

アプリケーションをZendeskに登録する

管理者は、ZendeskへのAPIコールを認証するために使用できるOAuth資格情報を生成するよう、アプリケーションを登録する必要があります。

メモ：このセクションでは、1個のZendeskアカウントを共用するユーザー用のOAuthクライアントの設定方法について説明します。1個のZendeskアカウントだけではなく、多数のZendeskアカウントとアプリケーションがやりとりする場合、グローバルOAuthクライアントを要求することができます。グローバルOAuthクライアントは、複数のZendeskインスタンスに対してAPI認証を実行する安全かつクリーンな手段です。詳細については、「Set up a global OAuth client」を参照してください。

アプリケーションを登録するには

  1. 管理センターで、サイドバーの「 アプリおよびインテグレーション」をクリックし、「API」>「Zendesk API」を選択します。
  2. 「Zendesk API」ページの「OAuthクライアント」タブをクリックし、OAuthクライアントの一覧の右上にある「OAuthクライアントを追加」をクリックします。
  3. 次のフィールドに入力して、クライアントを作成します。
    • クライアント名：アプリケーションの名前を入力します。この名前が、アプリケーションへのアクセス許可をユーザーに求めるときにクライアント名として表示されます。また、Zendeskにアクセスできるサードパーティアプリのリストにも、この名前が表示されます。
    • 説明：省略可能です。ユーザーにアクセス許可を求める際に、ユーザーに表示するアプリの簡単な説明を入力します。
    • 会社名：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示する会社名です。この情報は、アクセスを付与しようとしている相手を識別するのに役立ちます。
    • ロゴ（オプション）：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示するロゴです。JPG、GIF、PNG形式の画像を指定できます。最適な結果を得るには、正方形の画像をアップロードします。画像のサイズは、認証ページに合わせて自動的に調整されます。
    • 一意のID：アプリ名として入力した名前が再フォーマットされ、自動的に設定されます。この名前は変更してもかまいません。
    • クライアントの種類：PublicまたはConfidential。OAuthのPublicクライアントは、モバイルアプリやWebアプリなど、資格情報を安全に保存できない環境で実行されるアプリケーションです。Publicクライアントの場合は、PKCEを使用する必要があります。OAuthのConfidentialクライアントは、資格情報を安全に保持できるセキュアなサーバー上で実行されます。Confidentialクライアントの場合は、PKCE、クライアントシークレット、またはその両方を使用することができます。詳しくは「OAuthクライアントの種類」を参照してください。
    • リダイレクトURL：ユーザーによるアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。URLは絶対URLでなければなりません。相対URL、https（localhostまたは127.0.0.1でない場合）、改行で区切られたURLは入力しないでください。
  4. 「保存」をクリックします。

    ページが更新され、事前に数値が入力された「シークレットキー」フィールドが新たに左下に表示されます。これが、OAuth2の仕様で指定されているclient_secret値です。

  5. 「シークレット」の値をクリップボードにコピーし、安全な場所に保存します。メモ：シークレット値のテキストボックスの幅より長い場合があるため、コピーする前には必ず、シークレット値全体を選択していることを確認してください。
    重要：セキュリティ上の理由で、シークレット全体が表示されるのは1回限りです。「保存」をクリックした後は、最初の9文字以外は表示されなくなります。
  6. 「保存」をクリックします。

アプリケーションの一意のIDとシークレットの値の使用については、次項で説明します。

OAuthクライアントの種類

Zendesk OAuthクライアントには、OAuthクライアントの作成時に渡されるkindプロパティがあり、以下のいずれかの値を指定できます。

  • Public：OAuthのPublicクライアントは、モバイルアプリやWebアプリなど、資格情報を安全に保存できない環境で実行されるアプリケーションです。Publicクライアントの場合は、PKCEを使用する必要があります。
  • Confidential：OAuthのConfidentialクライアントは、資格情報を安全に保持できるセキュアなサーバー上で実行されます。Confidentialクライアントの場合は、PKCE、クライアントシークレット、またはその両方を使用することができます。

詳細については、「クライアントの種類」を参照してください。

Zendesk OAuthクライアントタイプは、Zendesk Supportのチケット管理システムにのみ適用されます。Chat、会話、Sellではサポートされていません。

既存のZendesk OAuthクライアントは、現在 kindプロパティが unknownに設定されています。これらの既存クライアントは、kindプロパティがpublicまたはconfidentialのいずれかに更新されるまで、影響を受けないままです。管理センターで作成される新しいOAuthクライアントは、作成時にkindプロパティを設定する必要があります。

メモ：既存のZendesk OAuthクライアントを使用していて、kindプロパティを publicに変更する場合は、まずPKCEを実装する必要があります。これを行わないと、PKCEが直ちに必要となるため、クライアントが機能しなくなります。

管理センターで作成されるすべてのOAuth新しいクライアントについて、kindプロパティを必ず設定してください。api/v2/oauth/clients endpointエンドポイントで作成したOAuthクライアントではkindプロパティは必須ではありませんが、Zendeskではこのプロパティを含めることを推奨しています。

OAuth認証フローをアプリケーションに実装する

Zendeskは、アクセストークンを取得するための認可コードグラントフローをサポートしています。このフローでは、アクセストークンをリクエストする前に認可コードを取得する必要があるため、Authorization Code Grant Flow（認可コードグラントフロー）と呼ばれています。それ以外のグラントフローは非推奨となりました。

このフローは更新トークンを使用しません。アクセストークンは期限切れになりません。

Authorization Code Grant Flowを実装するには、以下の機能をアプリケーションに追加する必要があります。

  • ステップ1 - ユーザーをZendeskの認可ページに送る
  • ステップ2 - 認可に関するユーザーの決定を処理する
  • ステップ3 - Zendeskからアクセストークンを取得する
  • ステップ4 - APIコールでアクセストークンを使用する

OAuth認証フローを実装するWebアプリを開発するチュートリアルについては、「OAuth Webアプリの開発」を参照してください。

認証コード付与メソッドは Proof Key for Code Exchange（PKCE）をサポートしています。詳細については、開発者向けドキュメントの「Using PKCE to make Zendesk OAuth access tokens more secure」を参照してください。

ステップ1 - ユーザーをZendeskの認可ページに送る

最初に、アプリケーションはユーザーをZendeskの認可ページに送る必要があります。このページでユーザーは、アプリケーションがユーザー自身の代理としてZendeskにアクセスすることを認可するよう求められます。ユーザーが認可または不認可を選択すると、Zendeskは選択内容とその他若干の情報をアプリケーションに送り返します。

ユーザーをZendeskの認可ページに送るには

アプリケーションに、ユーザーを次のURLに送るリンクボタンを追加します。

https://{subdomain}.zendesk.com/oauth/authorizations/new

{subdomain}にはZendeskのサブドメインを入力します。POSTリクエストとGETリクエストのどちらを使用してもかまいません。以下のパラメータを含めます。

  • response_type：必須。Zendeskは応答で認可コードを返すので、応答タイプとしてcodeを指定します。例：response_type=code
  • redirect_uri：必須。ユーザーのアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。相対URLではなく、絶対URLを指定する必要があります。また、localhostまたは127.0.0.1を使用している場合を除き、セキュア接続（https）を指定してください。
  • client_id：必須。アプリケーションをZendeskに登録したときに取得した一意のIDを指定します。前のセクションを参照してください。
  • scope：必須。Zendeskリソースへのアクセスを制御するスコープをスペースで区切って列挙します。すべてのリソースあるいは特定のリソースに対する読み取りアクセス、書き込みアクセス、またはなり代わりアクセスを要求できます。「スコープを設定する」を参照してください。
  • state：ユーザーがアクセスを許可するか拒否するかを決定した後のZendeskからの応答に含まれる任意の文字列。このパラメータを使用して、クロスサイトリクエストフォージェリ（CSRF）攻撃を防ぐことができます。CSRF攻撃では、エンドユーザーを騙して、ログイン中のWebアプリケーション内で意図しない操作を実行するリンクをクリックさせるように誘導します。この種の攻撃から防御するには、stateパラメータにいくつか値を追加し、その戻り値を検証します。
  • code_challenge：PKCEを使用する場合は必須。コードベリファイアから得られるコードチャレンジを表す文字列。詳しくは、開発者向けドキュメントの「Generating the code_challenge value」を参照してください。
  • code_challenge_method：PKCEを使用する場合は必須。コードチャレンジの取得に使用するメソッド。値として「S256」を指定します。

パラメータは必ずURLエンコードするようにしてください。

GETリクエストの例

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

エンドユーザーのブラウザにZendeskの認可ページが開きます。認可するかどうかを選択した後、選択内容が、リクエスト内に指定されたリダイレクトURLに送信されます。

スコープを設定する

アプリのZendeskリソースへのアクセスを制御するには、スコープを指定する必要があります。readスコープは、アプリにGETエンドポイントへのアクセスを与えます。これには、関連リソースをサイドロードするアクセス許可が含まれます。writeスコープは、アプリにPOST、PUT、DELETEの各エンドポイントに対してリソースの作成、更新、削除を行うアクセス許可を与えます。

スコープについて詳しくは、「OAuth Tokens for Grant Types」を参照してください。

impersonateスコープでは、Zendeskの管理者がエンドユーザーの代理でリクエストを作成することができます。「Making API requests on behalf of end users（エンドユーザーの代理でAPIリクエストを作成する方法）」を参照してください。

たとえば、次のパラメータは、すべてのリソースに対する読み取りアクセスをアプリに付与します。

"scope": "read"

次のパラメータは、すべてのリソースに対する読み取りおよび書き込みアクセスを付与します。

"scope": "read write"

次のリソースに対するスコープを詳細に調整できます。

  • チケット
  • ユーザー
  • 監査ログ（読み取り専用）
  • 組織
  • ヘルプセンター
  • アプリ
  • トリガ
  • 自動化
  • ターゲット
  • Webhook
  • zis

シンタックスは以下のようになります。

"scope": "resource:scope"

たとえば、次のパラメータは、アプリのアクセスをチケットの読み取りのみに制限します。

"scope": "tickets:read"

アプリにリソースへの読み取りと書き込みのアクセスを両方付与するには、両方のスコープを指定します。

"scope": "users:read users:write"

アプリに対して、1つのリソース（組織など）への書き込みアクセスと、それ以外の全リソースへの読み取りアクセスを付与するには、次のように指定します。

"scope": "organizations:write read"

ステップ2 - 認可に関するユーザーの決定を処理する

アプリケーションは、ユーザーの決定を通知するZendeskからの応答を処理する必要があります。この情報は、リダイレクトURL内のURLパラメータに含まれています。

ユーザーがアプリケーションにアクセスを付与するよう決定した場合、リダイレクトURLには認可コードが含まれます。以下に例を示します。

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

認証コードは120秒しか有効ではありません。

ユーザーがアプリケーションへのアクセスを許可しないと決めた場合、リダイレクトURLには、ユーザーがアクセスを拒否したことをアプリに通知するerrorパラメータとerror_descriptionパラメータが含まれます。

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

これらの値を使用してアプリケーションのフローを管理します。URLにcodeパラメータが含まれる場合、次項で説明するように、Zendeskからアクセストークンを取得します。これはZendeskへのAPIコールに含めるトークンです。

ステップ3 - Zendeskからアクセストークンを取得する

ユーザーがアプリケーションにZendeskへのアクセスを許可し、その応答としてZendeskから認可コードを受け取った場合、アプリケーションはそのコードをアクセストークンと交換することができます。アクセストークンを取得するには、以下のエンドポイントに対するPOSTリクエストを作成します。

https://{subdomain}.zendesk.com/oauth/tokens
メモ：このエンドポイントは、OAuth Tokens APIのCreate Tokenエンドポイントと混同しないようにしてください。どちらのエンドポイントも有効なOAuthアクセストークンを返しますが、エンドポイントは同じパス、同じJSONフォーマット、同じリクエストパラメータを共有していません。

リクエストには以下の必須パラメータを含めます。

  • grant_type："authorization_code"の値を指定します。
  • code：ユーザーがアクセスを付与された後でZendeskから受け取った認可コードを使用します。
  • client_id： Support管理インターフェイス（「管理」>「チャネル」>「API」>「OAuthクライアント」）のOAuthクライアントで指定された一意のIDを使用します。「アプリケーションをZendeskに登録する」を参照してください。
  • client_secret： Support管理インターフェイス（「管理」>「チャネル」>「API」>「OAuthクライアント」）のOAuthクライアントで指定されたシークレットを使用します。「アプリケーションをZendeskに登録する」を参照してください。

    code_challengeとcode_verifierのPKCEパラメータを使用する場合、client_secretは必要ありません。この特性を使用して、セキュリティ上の懸念から推奨されなくなったImplicit Grant Flow（インプリシットグラントフロー）から移行することができます。詳しくは、開発者向けドキュメントの「Using PKCE to migrate from the implicit grant flow」を参照してください。

  • redirect_uri：ステップ1のリダイレクトURLと同じURLです。ID目的のみ。
  • scope：「スコープを設定する」を参照してください。
  • code_verifier：PKCEを使用する場合は必須。code_challengeの値を生成するための文字列。詳しくは、開発者向けドキュメントの「Generating the code_challenge value」を参照してください。

リクエストはhttps経由で送信し、プロパティはJSON形式でフォーマットする必要があります。カスタムまたはサードパーティのアプリケーションを使用してAPIリクエストを行う場合、プロパティ値の適切なフォーマットについては、そのアプリケーションのドキュメントを参照してください。

curlの使用例

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

応答の例

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

ステップ4 - APIコールでアクセストークンを使用する

アプリは、アクセストークンを使用して、APIコールを実行できます。トークンをリクエストのHTTP認可ヘッダーに以下のように指定します。

Authorization: Bearer {a_valid_access_token}

たとえば、チケットをリストするcurlリクエストは以下のようになります。

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