最終更新日: 2025年8月28日
非公開アプリ(Private App)では、HubSpotのAPIを使用して、HubSpotアカウント上の特定のデータにアクセスできます。非公開アプリで何をリクエストまたは変更できるかは、アカウント側で非公開アプリごとに管理できます。権限が付与されると、そのアプリ専用のアクセストークンが生成されます。 HubSpotアカウント内で非公開アプリにアクセスするには、スーパー管理者権限が必要です。

注:

非公開アプリでは、カスタム タイムライン イベントがサポートされません。Webhookは非公開アプリでサポートされていますが、配信登録については、APIを介してプログラムで編集することはできません。代わりに、非公開アプリの設定で編集する必要があります。カスタム タイムライン イベントを使用するアプリを作成する予定であれば、代わりに公開アプリを作成してください。詳しくは非公開アプリと公開アプリの違いをご確認ください。

非公開アプリを作成する

  • HubSpotアカウントにて、メイン ナビゲーション バーの設定アイコンをクリックします。
  • 左のサイドバーメニューで[連携]>[非公開アプリ]の順に進みます。
  • [非公開アプリを作成]をクリックします。
  • [基本情報]タブでアプリの詳細を設定します。
    • アプリの名前を入力します。
    • 名前プレースホルダーロゴにカーソルを合わせ、表示されたアップロードアイコンをクリックして、アプリのロゴとして使用する正方形の画像をアップロードします。
    • アプリの説明を入力します。
  • [スコープ]タブをクリックします。
  • ページ上部の[新しいスコープを追加]をクリックします。
  • 右側のパネルで、非公開アプリがアクセスできるように設定する各スコープのチェックボックスをオンにします。
    • [スコープを検索]検索バーを使用して、特定のスコープを探すこともできます。使用可能なスコープを網羅したリストは、こちらのリファレンス記事でご確認いただけます。
    • スコープの追加が完了したら、[更新]をクリックします。アプリに追加のスコープが必要であると後で判断した場合は、アプリの作成後にスコープを構成することもできます。
非公開アプリの更新されたスコープ構成パネル
  • アプリに対して選択したスコープを確認します。アプリに必要ないと判断したスコープは、スコープ名の横の[削除]をクリックして削除できます。[選択されたスコープの概要]をクリックすると、アプリのスコープの詳細と各スコープに付与されている関連アクセス権も表示できます。
非公開アプリの更新されたスコープ構成ページ
  • アカウント内のCRMオブジェクトに対する変更によってトリガーされるイベントを受信するには、非公開アプリのWebhook配信登録を設定します。
    • ページ上部の[Webhook]タブをクリックします。
    • [ターゲットURL]に、イベントがトリガーされたときにHubSpotでPOSTリクエストを送信する宛先のURLを入力します。
    • [配信登録を作成]をクリックします。
    • 右側のパネルで、配信登録するオブジェクトタイプを選択し、HubSpotによる設定したエンドポイントへのリクエスト送信をトリガーするこれらのオブジェクトに関連付けられているイベント(作成、マージ、削除など)を選択します。
    • 選択したオブジェクトタイプに追加の未承認のスコープが必要な場合は、それらのスコープをアプリに追加するように求められます。
    • イベントタイプとして[プロパティーの変更]を選択した場合は、変更を配信登録する関連オブジェクトプロパティーを選択できます。
    • [配信登録]をクリックします。
非公開アプリで新しいWebhook配信登録を作成
  • Webhook配信登録をすぐに有効にしたくない場合、または誤って作成した配信登録を削除する場合は、Webhookの上にカーソルを置いて、そのステータスを管理するか、配信解除して削除するか、配信登録の詳細を確認することができます。非公開アプリでのWebhook配信登録の使用方法については、こちらの記事をご参照ください。
非公開アプリのWebhook設定を編集1
  • アプリの設定が完了したら、右上の[アプリを作成]をクリックします。
  • ダイアログボックスで、アプリのアクセストークンの情報を確認してから、[作成を続行]をクリックします。
アプリの作成が完了したら、アプリのアクセストークンを使用して、API呼び出しを開始できます。アプリの情報を編集したり、アプリのスコープを変更したりする必要がある場合は、アプリの詳細ページの右上にある[アプリを編集]をクリックします。
非公開アプリの作成後に詳細を編集

アプリのアクセストークンでAPI呼び出しを行う

注:

HubSpotアカウントがダウングレードされ、機能が利用できなくなると、非公開アプリはスコープを使用できなくなります。例えば、アカウントがHubDBにアクセスできない場合、非公開アプリはHubDBスコープにアクセスできません。非公開アプリのアクセストークンは、HubSpotアカウントで利用可能なスコープと非公開アプリ用に設定した内容を反映するように更新されますが、トークン文字列自体は変更されません。
API呼び出しを開始するには、アプリの詳細ページを開きます。
  • HubSpotアカウントにて、メイン ナビゲーション バーの設定アイコンをクリックします。
  • 左のサイドバーメニューで[連携]>[非公開アプリ]の順に進みます。
  • アプリの名前をクリックします。
  • [認証]タブで[トークンを表示]をクリックして、アクセストークンを表示します**。**[コピー]をクリックして、トークンをクリップボードにコピーします。
非公開アプリのアクセストークンを表示
  • アクセストークンを貼り付けて、開発者に提供したり、ご自身でアプリを開発する際に使用したりできます。HubSpot APIエンドポイントに対して呼び出しを行う際には、「Authorization」フィールドに**「Bearer [YOUR_TOKEN]」**という値を設定します。例えば、Node.jsとaxiosを使用してコンタクトAPIの呼び出しを行う場合、リクエストは以下のようになります。
axios.get(
  'https://api.hubapi.com/crm/v3/objects/contacts',
  {
    headers: {
      Authorization: `Bearer ${YOUR_TOKEN}`,
      'Content-Type': 'application/json',
    },
  },
  (err, data) => {
    // Handle the API response
  }
);
  • 非公開アプリのアクセストークンはOAuthを基盤として実装されているため、HubSpotのクライアントライブラリーを使用して、アクセストークンによる認証済みの呼び出しを行うこともできます。例えば、Node.jsクライアントライブラリーを使用する場合は、アプリのアクセストークンを渡すことにより、OAuthクライアントをインスタンス化できます。
const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN });

注:

非公開アプリを最初に作成したユーザーを削除すると、以前にアプリのアクセストークンを使用していたAPI呼び出しが"USER_DOES_NOT_HAVE_PERMISSIONS"resultで失敗します。この問題が発生した場合は、以下のセクションの手順に従ってアクセストークンをローテーションすることをお勧めします。誤ってアカウントからユーザーを削除してしまった場合は、追加し直すと問題が解決します。

非公開アプリのアクセストークン情報を表示する

非公開アプリのアクセストークンに関する情報(Hub IDや、トークンに関連付けられているスコープなど)を表示するには、/oauth/v2/private-apps/get/access-token-infoPOSTリクエストを送信します。以下のようにリクエスト本文にアクセストークンを含めます。
// POST request response body
{
  "tokenKey": {{accessToken}}
}
レスポンスには、トークンを作成したユーザー、アカウントのHub ID、非公開アプリのID、トークンに関連付けられているスコープに関する情報が格納されています。
// Example response for GET request to /oauth/v2/private-apps/get/access-token-info
{
  "userId": 123456,
  "hubId": 1020304,
  "appId": 2011410,
  "scopes": ["oauth", "crm.schemas.companies.write"]
}

アクセストークンをローテーションする

アクセストークンが分からなくなった場合や侵害された場合は、トークンをローテーション(変更)できます。新しいアクセストークンが作成され、元のアクセストークンは失効します。
  • HubSpotアカウントにて、メイン ナビゲーション バーの[設定]ページをクリックします。
  • [連携]>[非公開アプリ]の順に進みます。
  • 非公開アプリの名前をクリックします。
  • アクセストークンの横にある[変更(ローテーション)]をクリックします。
    • トークンが侵害され、直ちにアクセスを取り消す場合は、[今すぐこのトークンを変更(ローテーション)して期限切れにする]をクリックします。
    • 特に侵害が生じていなくても、トークンは6か月ごとに変更することが推奨されます。トークンを定期的に変更する準備ができている場合は、[後でこのトークンを変更(ローテーション)して期限切れにする]をクリックします。これにより、7日後にトークンが失効します。
      • アプリを早く移行する準備ができている場合は、[今すぐ期限切れにする]をクリックします。
      • もっと時間が必要だと判断した場合は、[変更(ローテーション)をキャンセル]をクリックし、元のトークンの失効を取り消して、新しいアクセストークンを無効にすることができます。
非公開アプリのアクセストークンのローテーション
また、HubSpotは、アクセストークンのローテーションステータスに関するリマインダーやその他の関連アラートを含むメール通知をスーパー管理者に送信します。HubSpotアカウントのスーパー管理者は、以下のイベントとリマインダーの通知を受け取ります。
  • スーパー管理者がローテーションを開始したとき(今すぐ実行する場合、または7日後に実行する場合)。
  • スーパー管理者が保留中のローテーションをキャンセルしたとき。
  • スーパー管理者が、トークンの有効期限が切れるまで7日待つのではなく、[今すぐ期限切れにする]をクリックして、アクセストークンをすぐに失効させることを選択したとき。
  • アプリのアクセストークンが24時間後に期限切れになるとき。
  • 7日間が経過し、アプリのアクセストークンがローテーションされて期限切れになったとき。
  • アクセストークンを180日以上ローテーションしていないときにも、スーパー管理者にアプリのアクセストークンをローテーションするリマインダーメールが届きます。

API呼び出しログを表示する

アプリによる過去30日間のAPI呼び出しを確認するには、以下の操作を行います。
  • アプリの詳細ページで[ログ]タブをクリックします。
  • 非公開アプリのAPI呼び出しの確認と絞り込みを行うには、以下の操作を行います。
    • [メソッド]または[レスポンス]ドロップダウンメニューをクリックして、リクエストメソッドまたはレスポンスコードでAPI呼び出しの履歴を絞り込みます。
    • [開始日]または[終了日]ドロップダウンメニューをクリックして、特定の期間でAPI呼び出しログを絞り込みます。
    • [リクエストURLで検索]検索ボックスで、URLを指定して特定の呼び出しを検索することもできます。
非公開アプリのログタブ

注:

HubSpotは、成功したAPI呼び出しのリクエスト本文、リクエストURLパラメーター、またはレスポンスペイロードを非公開アプリのログに保存しません。このデータをトラッキングする場合、または30日以上前のログデータを保存する場合は、アプリの履歴呼び出しの外部ログを保持することをお勧めします。
  • API呼び出しログをエクスポートするには、[ログをエクスポート(CSV)]をクリックします。次に、日付範囲(最長で過去30日まで)を指定し、[エクスポート]をクリックします。
  • ポップアップボックスで、エクスポートするAPI呼び出しの日付範囲を選択し、[エクスポート]をクリックします。エクスポートが完了すると、ダウンロードリンクが記載されたEメールが届きます。

非公開アプリに関する制限

HubSpotアカウント1件につき、最大20件の非公開アプリを作成できます。各非公開アプリには、HubSpotのAPI利用ガイドラインが適用されます。非公開アプリから実行できる呼び出しの回数は、以下のようにアカウントのご契約内容とAPI追加オプションのご購入状況に基づきます。
製品のエディション10秒当たり1日当たり
非公開アプリ(全ての製品の)無料ツールおよびStarter非公開アプリごとに100回アカウントごとに250,000回
(全ての製品の)Professional非公開アプリごとに190回アカウントごとに625,000回
(全ての製品の)Enterprise非公開アプリごとに190回アカウントごとに1,000,000回
非公開アプリ(APIの上限数の引き上げを購入)(全ての製品の)無料ツール、Starter、Professional、Enterprise非公開アプリごとに200回基本となるご契約エディションの呼び出し回数に加えて、購入した上限の引き上げ1単位につき、アカウントごとの呼び出し数が1,000,000回増加。APIの上限数の引き上げは最大2単位まで購入できます。
StarterプランとProfessionalプランの両方を利用している場合、上位プラン(Professional)の制限がアカウントに適用されます。 /account-info/v3/api-usage/daily/private-appsGETリクエストを送信して、HubSpotアカウントの全ての非公開アプリの毎日のAPI使用状況を確認できます。詳しくは、アカウント情報APIの使用方法についてご参照ください。

注:

APIの上限数の引き上げを購入すると、関連付けAPIに対して実行できるリクエストの最大数が1日当たり1,000,000回、10秒当たり200回に引き上げられます。ただしこれらの制限は、API制限の引き上げをさらに追加購入してそれ以上増やすことはできません

非公開アプリを削除する

非公開アプリを削除すると、そのアプリのアクセストークンは永久に取り消され、API呼び出しにも使用できなくなります。 アプリを削除するには、以下の操作を行います。
  • HubSpotアカウントにて、メイン ナビゲーション バーの設定アイコンをクリックします。
  • 非公開アプリの名前をクリックします。
  • ページ上部の[認証]タブをクリックします。
  • ページの最下部に表示される[[アプリ名]を削除]をクリックします。
  • ダイアログボックスにアプリの名前を入力して削除を確認し、[削除]をクリックします。