OAuthの利用

OAuthはアプリをユーザーアカウントに接続するための安全な認証手段で、パスワードではなく認証トークンが使用されます。ユーザーが自分のHubSpotアカウント上にアプリをインストール(英語)することを許可するためには、まずOAuthのアクセスを開始します。

注:複数のHubSpotアカウントによるインストール用に設計されたアプリ、またはアプリマーケットプレイスに掲載されるアプリでは、OAuthを使用する必要があります。 

参考資料
  • OAuthクイックスタートガイドで紹介されているサンプルアプリは、OAuth 2.0の利用をできるだけ短時間で開始することを意図して設計されており、全ての手順を実際にご利用いただけます。
  • HubSpotアカデミーのコース(英語)では、HubSpotでOAuthを使い始めるための導入について、短時間で習得できます。HubSpot-OAuthフローの詳細や、アクセストークンの更新方法を説明しています。

OAuth 2.0との連携を開始する

OAuth 2.0との連携を開始するために必要な手順は以下です。

  • まずHubSpot開発者アカウントアプリを作成します。アプリを作成すると、アプリ設定の認証ページで作成したアプリのクライアントIDとクライアントシークレットを確認できるようになります。

MyHubSpotApp画像

  • 下記のように、クライアント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
  • access_tokenを使用して、該当のHubSpotアカウントに対して行われたAPI呼び出しを認証します。 
  • access_tokenの有効期限が切れたら、refresh_tokenを使用して新しいaccess_tokenを生成します。

注:

  • リフレッシュトークンと初期アクセストークンを生成しない限り、ユーザーのアカウントに貴社のアプリが[接続されたアプリ]として表示されることはありません。 
  • アクセストークンはアプリから要求されたスコープを反映しますが、ユーザーがHubSpotアカウントで実行する操作に関する権限や制限は反映しません。例えば、ユーザーに自分が担当するコンタクトのみを表示する権限が付与されている場合、このユーザーがcrm.objects.contacts.readスコープに対する要求を許可したとすると、生成されるアクセストークンでは、許可したユーザーが担当するコンタクトだけでなく、アカウント内の全てのコンタクトを表示できます。 

クエリーパラメーター

アプリの認証URLを作成する際には、以下のパラメーターが必須です。

必要なパラメーター
パラメーター 説明 使い方
クライアントID client_id=x
URLで使用
アプリの認証設定ページから(上記の説明に従って)取得します。
リダイレクト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のみのアカウントを使用している顧客も、全てのスコープにはアクセスできなくても、アプリを認証できるようになります。認証されていない全てのスコープについては、アプリ側で確認および処理する必要があります。


スコープ 説明 提供するアクセス 必須アカウントティア
automation ワークフローが含まれます。 自動化API(ワークフローエンドポイント) Marketing Hub ProfessionalまたはEnterprise
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
crm.lists.read コンタクトリストに関する詳細を表示します。 リストエンドポイント 全てのアカウント
crm.lists.write コンタクトリストを作成、削除、または変更します。 リストエンドポイント 全てのアカウント
crm.objects.companies.read 会社のプロパティーやその他の詳細を表示します。 会社エンドポイント 全てのアカウント
crm.objects.companies.write 会社のプロパティーの表示、および会社の作成、削除、または変更を行います。 会社エンドポイント 全てのアカウント
crm.objects.contacts.read コンタクトのプロパティーやその他の詳細を表示します。 コンタクトエンドポイント 全てのアカウント
crm.objects.contacts.write コンタクトのプロパティーの表示、およびコンタクトの作成、削除、または変更を行います。 コンタクトエンドポイント 全てのアカウント
crm.objects.deals.read 取引のプロパティーやその他の詳細を表示します。 取引エンドポイント 全てのアカウント
crm.objects.deals.write 取引のプロパティーの表示、および取引の作成、削除、または変更を行います。 取引エンドポイント 全てのアカウント
crm.objects.owners.read CRMレコードに割り当てられたユーザーに関する詳細を表示します。 担当者エンドポイント 全てのアカウント
crm.schemas.companies.read 会社のプロパティー設定に関する詳細を表示します。 プロパティーエンドポイント 全てのアカウント
crm.schemas.companies.write 会社のプロパティー設定を作成、削除、または変更します。 プロパティーエンドポイント 全てのアカウント
crm.schemas.contacts.read コンタクトのプロパティー設定に関する詳細を表示します。 プロパティーエンドポイント 全てのアカウント
crm.schemas.contacts.write コンタクトのプロパティー設定を作成、削除、または変更します。 プロパティーエンドポイント 全てのアカウント
crm.schemas.deals.read 取引のプロパティー設定に関する詳細を表示します。 プロパティーエンドポイント 全てのアカウント
crm.schemas.deals.write 取引のプロパティー設定の作成、削除、または変更を行います。 プロパティーエンドポイント 全てのアカウント
content サイト、ランディングページ、Eメール、ブログ、キャンペーンが含まれます。 CMS API、およびカレンダー、Eメール、Eメールイベントのエンドポイント CMS HubのProfessionalまたはEnterpriseMarketing HubのProfessionalまたはEnterprise
conversations.read コミュニケーション受信トレイ内のスレッドの詳細を表示します。 コミュニケーション受信トレイおよびメッセージAPI 全てのアカウント
conversations.visitor_identification.tokens.create HubSpotチャットウィジェットでやり取りを行っている、認証済みのウェブサイト訪問者の識別トークンを取得します。 訪問者の識別API ProfessionalまたはEnterpriseエディション
crm.import レコードをCRMにインポートするために使用します。全てのタイプのCRMデータ(コンタクト、会社、取引、チケットなど)の新しいレコードの作成、または既存のレコードの変更が含まれます。データのアーカイブや削除は含まれません。 CRMインポートAPI 全てのアカウント
cms.source_code.read_write 開発者によるウェブサイトおよびEメールのコードの記述に必要なファイル(テンプレートやモジュールなど)をアップロードおよびダウンロードする権限を付与します。 コンテンツ ファイル マッパーAPI、CMSモジュールAPI、CMSレイアウト、CMSテンプレートAPI CMS Hubの ProfessionalまたはEnterpriseMarketing HubのProfessionalまたはEnterprise
e-commerce eコマース機能へのアクセス権が含まれます。 製品と商品項目のエンドポイント

全てのアカウント

注:製品APIでこのスコープを使用できるのは、ProfessionalおよびEnterpriseエディションのみとなります。

files ファイルマネージャーへのアクセス権が含まれます。 ファイル(ファイルマネージャー)とファイルマッパー(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メールエンゲージメントのコンテンツを取得するには、このスコープが必要です。詳細についてはエンゲージメントの概要をご確認ください。
全てのアカウント
settings.user.read HubSpotアカウントからユーザーおよびユーザーロールを取得します。 User Provisioning API

全てのアカウント

注:このスコープを使用してユーザーロールを取得できるのは、Enterpriseエディションのみです。

settings.user.teams.read HubSpotのアカウントからチームを取得します。 User Provisioning API

ProfessionalまたはEnterpriseエディション

social ソーシャル機能が含まれます。 ソーシャルメディアAPI Marketing Hub ProfessionalまたはEnterprise
tickets チケットへのアクセス権が含まれます。 チケットエンドポイント 全てのアカウント
timeline HubSpot CRMレコードでカスタムイベントを管理するためのアクセス権を許可します。レコードの作成または更新が含まれます。 タイムラインイベントのエンドポイント 全てのアカウント
transactional-email トランザクションEメールとトランザクションEメールのエンドポイントが含まれます。 トランザクションEメールのエンドポイント トランザクションEメール追加オプション(英語)が有効なMarketing Hub ProfessionalまたはEnterprise

関連ドキュメント