OAuthの利用｜HubSpot（ハブスポット）
OAuthはアプリをユーザーアカウントに接続するための安全な認証手段で、パスワードではなく認証トークンが使用されます。ユーザーが自分のHubSpotアカウント上にアプリをインストール（英語）することを許可するためには、まずOAuthのアクセスを開始します。
注：
- 複数のHubSpotアカウントによるインストール用に設計されたアプリ、またはアプリマーケットプレイスに掲載されるアプリでは、OAuthを使用する必要があります。
- HubSpotアカウントでアプリをインストールするユーザーは、スーパー管理者の権限、またはアプリマーケットプレイスのアクセス権限を付与されている必要があります。
参考資料
- OAuthクイックスタートガイドで紹介されているサンプルアプリは、OAuth 2.0の利用をできるだけ短時間で開始することを意図して設計されており、全ての手順を実際にご利用いただけます。
- HubSpotアカデミーのコース（英語）では、HubSpotでOAuthを使い始めるための導入について、短時間で習得できます。HubSpot-OAuthフローの詳細や、アクセストークンの更新方法を説明しています。
OAuth 2.0との連携を開始するために必要な手順は以下です。
- まず、HubSpot開発者アカウントでアプリを作成します。アプリを作成すると、アプリ設定の認証ページで作成したアプリのクライアントIDとクライアントシークレットを確認できるようになります。
- 下記のように、クライアントIDとクライアントシークレット、およびクエリーパラメーターとスコープを使用して、認証URLを作成します。
- アプリをインストールするユーザーを認証URLに誘導し、ユーザーがアカウントを選択する画面を表示して、連携機能へのアクセスを許可できるようにします。アクセスを許可したユーザーには、コード クエリー パラメーターが付加された
redirect_url経由のリダイレクトにより、アプリが再表示されます。貴社はこのコードとクライアントシークレットを使用して、HubSpotからaccess_tokenとrefresh_tokenを取得することになります。- 認証URLの例：
https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/ - リダイレクトURLの例：
https://www.example.com/?code=xxxx - エラーの例：
https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
- 認証URLの例：
access_tokenを使用して、該当のHubSpotアカウントに対して行われたAPI呼び出しを認証します。access_tokenの有効期限が切れたら、refresh_tokenを使用して新しいaccess_tokenを生成します。
注：
- リフレッシュトークンと初期アクセストークンを生成しない限り、ユーザーのアカウントに貴社のアプリが［接続されたアプリ］として表示されることはありません。
- アクセストークンはアプリから要求されたスコープを反映しますが、ユーザーがHubSpotアカウントで実行する操作に関する権限や制限は反映しません。例えば、ユーザーに自分が担当するコンタクトのみを表示する権限が付与されている場合、このユーザーが
crm.objects.contacts.readスコープに対する要求を許可したとすると、生成されるアクセストークンでは、許可したユーザーが担当するコンタクトだけでなく、アカウント内の全てのコンタクトを表示できます。
アプリの認証URLを作成する際には、以下のパラメーターが必須です。
| パラメーター | 説明 | 使い方 |
|---|---|---|
| クライアントID | client_id=xURLで使用 |
アプリの認証設定ページから（上記の説明に従って）取得します。 |
| リダイレクトURL | redirect_uri=xアプリへのアクセスを許可した後の訪問者のリダイレクト先URL |
アプリの認証設定ページでも指定します。 注：セキュリティー上の理由により、本番環境ではこのURLに必ずHTTPSを使用する必要があります（localhostを使用したテスト環境では、HTTPを使用することも可能です）。また、IPアドレスはサポートされていないため、必ずドメインを使用してください。 |
| スコープ | scope=x%20x |
貴社のアプリに対するアクセス許可（許可ごとにスペースで区切ります）。アプリの認証設定でチェックマークを付けたスコープは必須と見なされるため、このパラメーターに含めない場合は認証ページにエラーが表示されます。 また、ここに含まれたスコープへのアクセス権がないアカウント上にアプリをインストールしようとした場合、エラーが発生します。 |
以下のパラメーターは任意で指定できます。
| パラメーター | 使い方 | 説明 |
|---|---|---|
| 任意指定のスコープ | &optional_scope=x%20x |
貴社のアプリに対する任意アクセス許可（許可ごとにスペースで区切ります）。ユーザーがそのツールへのアクセス権を持っていないHubSpotアカウントを選択した場合（CRM専用ポータルでソーシャルスコープをリクエストする場合など）、任意指定のスコープは自動的に認証リクエストから除かれます。任意指定のスコープを使用する場合、許可されたスコープを知るためにはアクセストークンまたはリフレッシュトークンを確認する必要があります。スコープの詳細については下記の表を参照してください。 |
| 状態 | &state=y認証URLにこのパラメーターを含めた場合、ここで指定した値がredirect_urlに誘導される際のstateクエリーパラメーターに含められます。 |
リダイレクトされてアプリに戻ってきたユーザーの状態を維持するために使用できる文字列値。 |
OAuthでは、アプリのスコープまたはアクセス許可の設定が必要です。各スコープによって、一連のHubSpot APIエンドポイントへのアクセス権が与えられます。また、アプリによるHubSpotアカウント上の特定のツールへのアクセスを、ユーザーが許可できるようになります。
特定のAPIまたはエンドポイントへのアクセスは、HubSpotアカウントのティアによって異なります。下記の表は、全ての利用可能なスコープとアクセス可能なエンドポイントの一覧です。複数の異なるHubSpotアカウント上で機能するアプリの場合は、optional_scopeパラメーターを使用して、対応するあらゆるティアのスコープを含めることができます。これにより、CRMのみのアカウントを使用している顧客も、全てのスコープにはアクセスできなくても、アプリを認証できるようになります。認証されていない全てのスコープについては、アプリ側で確認および処理する必要があります。
| スコープ | 説明 | 提供するアクセス | 必須アカウントティア |
|---|---|---|---|
cms.domains.read |
インテグレーターは、顧客のアカウントにCMSドメインを一覧表示できます。 | CMS API | 全てのアカウント |
cms.domains.write |
インテグレーターは、CMSカスタムドメインを作成、更新、および削除できます。 | CMS API | 全てのアカウント |
cms.functions.read |
インテグレーターは、全てのCMSサーバーレス関数、関連するシークレット、および関数の実行結果を表示できます。 | CMS API | CMS Hub Enterprise |
cms.functions.write |
インテグレーターは、CMSサーバーレス関数とシークレットを書き込むことができます。 | CMS API | CMS Hub Enterprise |
cms.knowledge_base.articles.read |
ナレッジ記事の詳細を表示できます。 | CMS API | Service Hub Professional／Enterprise |
|
|
ナレッジ記事を更新する権限を付与します。 | CMS API | Service Hub Professional／Enterprise |
cms.knowledge_base.articles.publish |
ナレッジ記事を更新および公開する権限を付与します。 | CMS API | Service Hub Professional／Enterprise |
cms.knowledge_base.settings.read |
ドメインやルートURLなどの一般的なナレッジベース設定とテンプレートのナレッジベース設定を表示できます。 | CMS API | Service Hub Professional／Enterprise |
cms.knowledge_base.settings.write |
一般的なナレッジベース設定とテンプレートのナレッジベース設定を更新する権限を付与します。これには、ナレッジ記事への書き込みアクセス権が含まれます。 | CMS API | Service Hub Professional／Enterprise |
cms.performance.read |
インテグレーターは、全てのサイトのCMSパフォーマンスデータを表示できます。 | CMS API | 全てのアカウント |
crm.lists.read |
コンタクトリストに関する詳細を表示します。 | リストエンドポイント | 全てのアカウント |
crm.lists.write |
コンタクトリストを作成、削除、または変更します。 | リストエンドポイント | 全てのアカウント |
crm.objects.companies.read |
会社のプロパティーやその他の詳細を表示します。 | 会社エンドポイント | 全てのアカウント |
crm.objects.companies.write |
会社のプロパティーの表示、および会社の作成、削除、または変更を行います。 | 会社エンドポイント | 全てのアカウント |
crm.objects.contacts.read |
コンタクトのプロパティーやその他の詳細を表示します。 | コンタクトエンドポイント | 全てのアカウント |
crm.objects.contacts.write |
コンタクトのプロパティーの表示、およびコンタクトの作成、削除、または変更を行います。 | コンタクトエンドポイント | 全てのアカウント |
crm.objects.custom.read |
HubSpot CRMでカスタムオブジェクトに関する詳細を表示できます。 | カスタム オブジェクト エンドポイント | 全ての「Enterprise」 |
crm.objects.custom.write |
HubSpot CRMでカスタムオブジェクトを作成、削除、または変更できます。 | カスタム オブジェクト エンドポイント | 全ての「Enterprise」 |
crm.objects.deals.read |
取引のプロパティーやその他の詳細を表示します。 | 取引エンドポイント | 全てのアカウント |
crm.objects.deals.write |
取引のプロパティーの表示、および取引の作成、削除、または変更を行います。 | 取引エンドポイント | 全てのアカウント |
crm.objects.feedback_submission.read |
フィードバックアンケートに対する送信に関する詳細を表示できます。 | フィードバック アンケート エンドポイント | Service Hub Professional／Enterprise |
crm.objects.goals.read |
全ての目標タイプを表示できます。 | 目標エンドポイント | Sales Hub Starter／Professional／Enterprise |
crm.objects.line_items.read |
商品項目のプロパティーやその他の詳細を表示できます。 | 商品項目エンドポイント | 全てのアカウント |
crm.objects.line_items.write |
商品項目を作成、削除、または変更できます。 | 商品項目エンドポイント | 全てのアカウント |
crm.objects.marketing_events.read |
マーケティングイベントに関する詳細を表示できます。 | マーケティング イベント エンドポイント | 全てのアカウント |
crm.objects.marketing_events.write |
マーケティングイベントを作成、削除、または変更できます。 | マーケティング イベント エンドポイント | 全てのアカウント |
crm.objects.owners.read |
CRMレコードに割り当てられたユーザーに関する詳細を表示します。 | 担当者エンドポイント | 全てのアカウント |
crm.objects.quotes.read |
見積もりおよび見積もりテンプレートのプロパティーやその他の詳細を表示できます。 | 見積もりエンドポイント | 全てのアカウント |
crm.objects.quotes.write |
見積もりを作成、削除、または変更できます。 | 見積もりエンドポイント | 全てのアカウント |
crm.schemas.companies.read |
会社のプロパティー設定に関する詳細を表示します。 | プロパティーエンドポイント | 全てのアカウント |
crm.schemas.companies.write |
会社のプロパティー設定を作成、削除、または変更します。 | プロパティーエンドポイント | 全てのアカウント |
crm.schemas.contacts.read |
コンタクトのプロパティー設定に関する詳細を表示します。 | プロパティーエンドポイント | 全てのアカウント |
crm.schemas.contacts.write |
コンタクトのプロパティー設定を作成、削除、または変更します。 | プロパティーエンドポイント | 全てのアカウント |
crm.schemas.custom.read |
HubSpot CRMでカスタムオブジェクト定義に関する詳細を表示できます。 | カスタム オブジェクト エンドポイント | 全ての「Enterprise」 |
crm.schemas.deals.read |
取引のプロパティー設定に関する詳細を表示します。 | プロパティーエンドポイント | 全てのアカウント |
crm.schemas.deals.write |
取引のプロパティー設定の作成、削除、または変更を行います。 | プロパティーエンドポイント | 全てのアカウント |
crm.schemas.line_items.read |
商品項目の詳細を表示できます。 | 商品項目エンドポイント | 全てのアカウント |
crm.schemas.quotes.read |
見積もりおよび見積もりテンプレートの詳細を表示できます。 | 見積もりエンドポイント | 全てのアカウント |
settings.billing.write |
アカウントの請求設定を変更できます。これには、ユーザーの有料シートの管理と割り当てが含まれます。 | 設定エンドポイント | 全てのアカウント |
settings.currencies.read |
既存の為替レートのほか、ポータルに関連付けられている現在の会社の通貨を読み取ることができます。 | アカウント情報エンドポイント | 全てのアカウント |
settings.currencies.write |
ポータルに関連付けられている会社の通貨を更新できるとともに、為替レートを作成、更新、削除できます。 | アカウント情報エンドポイント | 全てのアカウント |
settings.users.read |
アカウントユーザーおよびその権限に関する詳細を表示できます。 | ユーザー プロビジョニング エンドポイント | 全てのアカウント |
settings.users.write |
HubSpotアカウントのユーザーとユーザー権限を管理できます。これには、新しいユーザーの作成、権限と役割の割り当て、既存のユーザーの削除が含まれます。 | ユーザー プロビジョニング エンドポイント | 全てのアカウント |
settings.users.teams.read |
アカウントのチームに関する詳細を確認できます。 | ユーザー プロビジョニング エンドポイント | 全てのアカウント |
settings.users.team.write |
ユーザーをHubSpotアカウントのチームに割り当てることができます。 | ユーザー プロビジョニング エンドポイント | 全てのアカウント |
account-info.security.read |
アカウント アクティビティー ログやその他のアカウントセキュリティー情報へのアクセス権が含まれます。 | アカウントアクティビティーAPI | 全てのアカウント |
accounting |
HubSpotと会計・経理の連携で請求書、製品、コンタクトの詳細を共有できます。 | 会計拡張API | 全てのアカウント |
actions |
コンタクトのページにカスタムアクションを実行するフォームを追加できます。 | CRM拡張API | 全てのアカウント |
analytics.behavioral_events.send |
カスタム行動イベントを送信する権限が含まれます。 | アナリティクスAPI | Marketing Hub Enterprise |
automation |
ワークフローが含まれます。 | 自動化API（ワークフローエンドポイント） | Marketing Hub ProfessionalまたはEnterprise |
behavioral_events.event_definitions.read_write |
行動イベントを作成、読み取り、更新、または削除できます。これには、行動イベントのプロパティーが含まれます。 | アナリティクスAPI | Marketing Hub Enterprise |
business_units.view.read |
ロゴ情報を含むビジネス ユニット データを表示できます。 | APIビジネスユニットAPI | ビジネス ユニット アドオン |
business-intelligence |
ソースとEメールに関するエンドポイントが含まれます。 | アナリティクスAPI | 全てのアカウント |
collector.graphql_query.execute |
HubSpotアカウントからGraphQL APIエンドポイントを使用してデータのクエリーを実行します。 | GraphQL APIエンドポイント | CMS Hub ProfessionalまたはEnterprise |
collector.graphql_schema.read |
GraphiQLなどのGraphQLアプリケーションクライアントを介してイントロスペクションクエリーを実行します。 | GraphiQLおよびその他のサードパーティーのGraphQLクライアント | CMS Hub ProfessionalまたはEnterprise |
communication_preferences.read |
コンタクトの配信登録設定の詳細を表示できます。 | 配信登録設定API | 全てのアカウント |
communication_preferences.read_write |
配信登録タイプに対するコンタクトの配信登録／配信停止を行うことができます。配信停止したコンタクトは配信登録されません。 | 配信登録設定API | 全てのアカウント |
communication_preferences.write |
配信登録タイプに対するコンタクトの配信登録／配信停止を行うことができます。配信停止したコンタクトは配信登録されません。 | 配信登録設定API | 全てのアカウント |
content |
サイト、ランディングページ、Eメール、ブログ、キャンペーンが含まれます。 | CMS API、およびカレンダー、Eメール、Eメールイベントのエンドポイント | CMS HubのProfessionalまたはEnterprise、Marketing HubのProfessionalまたはEnterprise |
conversations.read |
コミュニケーション受信トレイ内のスレッドの詳細を表示します。 | コミュニケーション受信トレイおよびメッセージAPI | 全てのアカウント |
conversations.visitor_identification.tokens.create |
HubSpotチャットウィジェットでやり取りを行っている、認証済みのウェブサイト訪問者の識別トークンを取得します。 | 訪問者の識別API | ProfessionalまたはEnterpriseエディション |
conversations.write |
コミュニケーションでメッセージを送信できます。メッセージスレッドを作成、更新できます。 | コミュニケーション受信トレイおよびメッセージAPI | 全てのアカウント |
crm.export |
全てのCRMデータタイプのCRMからレコードをエクスポートできます。 | CRMエクスポートAPI | 全てのアカウント |
crm.import |
レコードをCRMにインポートするために使用します。全てのタイプのCRMデータ（コンタクト、会社、取引、チケットなど）の新しいレコードの作成、または既存のレコードの変更が含まれます。データのアーカイブや削除は含まれません。 | CRMインポートAPI | 全てのアカウント |
ctas.read |
CTAの読み取りアクセスを許可します。 | 利用可能なパブリックAPIなし | Marketing HubまたはCMS Hub Starter／Professional／Enterprise |
e-commerce |
eコマース機能へのアクセス権が含まれます。 | 製品と商品項目のエンドポイント |
全てのアカウント 注：製品APIでこのスコープを使用できるのは、ProfessionalおよびEnterpriseエディションのみとなります。 |
external_integrations.forms.access |
既存のフォームの名前変更、削除、複製を行うことができます。 | フォームエンドポイント |
全てのアカウント |
files |
ファイルマネージャーへのアクセス権が含まれます。 | ファイル（ファイルマネージャー）とファイルマッパー（CMSテンプレート、モジュール、レイアウト）のエンドポイント | 全てのアカウント |
files.ui_hidden.read |
全てのHubSpotツールに含まれるユーザーファイル、添付ファイル、システムファイルの詳細を表示したり、ダウンロードしたりできます。 | ファイル（ファイルマネージャー）とファイルマッパー（CMSテンプレート、モジュール、レイアウト）のエンドポイント | 全てのアカウント |
forms |
フォームエンドポイントへのアクセス権が含まれます。 | フォームエンドポイント | 全てのアカウント |
forms-uploaded-files |
フォーム経由で送信されたファイルをダウンロードします。 | フォーム送信エンドポイント経由でアップロードされたファイルの取得 | 全てのアカウント |
hubdb |
HubDBへのアクセス権が含まれます。 | HubDBエンドポイント | CMS HubのProfessionalまたはEnterprise、あるいはウェブサイト追加オプションが有効なMarketing HubのProfessionalまたはEnterprise |
integration-sync |
これによって公開される同期APIにより、ほとんどのCRMオブジェクトを同期できます。 | Ecommerce Bridge API | 全てのアカウント |
media_bridge.read |
メディアブリッジからイベントとオブジェクトへのアクセス権を許可します。 | メディアブリッジAPI | 全てのアカウント |
media_bridge.write |
メディアブリッジからイベントとオブジェクトを作成および更新するためのアクセス権を許可します。 | メディアブリッジAPI | 全てのアカウント |
oauth |
OAuthに必要な基本的なスコープ。このスコープは既定で全てのアプリに追加されます。 | 全てのアカウント | |
sales-email-read |
コンタクトに送信された1対1Eメールの全詳細の読み取りアクセスを許可します。 | エンゲージメントエンドポイント 注：Eメールエンゲージメントのコンテンツを取得するには、このスコープが必要です。詳細についてはエンゲージメントの概要をご確認ください。 |
全てのアカウント |
social |
ソーシャル機能が含まれます。 | ソーシャルメディアAPI | Marketing Hub ProfessionalまたはEnterprise |
tickets |
チケットへのアクセス権が含まれます。 | チケットエンドポイント | 全てのアカウント |
timeline |
HubSpot CRMレコードでカスタムイベントを管理するためのアクセス権を許可します。レコードの作成または更新が含まれます。 | タイムラインイベントのエンドポイント | 全てのアカウント |
transactional-email |
トランザクションEメールとトランザクションEメールのエンドポイントが含まれます。 | トランザクションEメールのエンドポイント | トランザクションEメール追加オプション（英語）が有効なMarketing Hub ProfessionalまたはEnterprise |
貴重なご意見をありがとうございました。
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。