OAuthの利用

OAuthは、アプリをユーザーアカウントに接続するためにパスワードではなく認証トークンを使用するセキュリティーで保護された認証手段です。OAuthのアクセスを開始することは、ユーザーが自分のHubSpotアカウント上にアプリをインストール(英語)できるようにするための最初のステップです。

すべてのアプリ開発者への注意事項:複数のHubSpotアカウントによるインストール用に設計されたアプリ、またはアプリマーケットプレイスに掲載されるアプリでは、OAuthを使用する必要があります。APIキーを使用している場合、アプリ掲載は却下されます。 

お勧めの参考資料

OAuth 2.0との連携を開始する

1.OAuthを使用するための最初のステップは、HubSpot開発者アカウントアプリを作成することです。これにより、アプリ設定の認証ページでアプリのクライアントIDとクライアントシークレットを確認できるようになります。

1-MyHubSpotApp

 

2.下記のように、クライアントIDとクライアントシークレット、およびクエリーパラメータースコープを使用して、認証URLを作成します。 

3.アプリをインストールするユーザーを認証URLに誘導し、ユーザーが(複数アカウントを利用している場合は)アカウントを選択する画面を表示して、連携機能へのアクセスを許可できるようにします。アクセスを許可した後、コード クエリー パラメーターが付加されたredirect_url経由のリダイレクトにより、ユーザーはアプリに戻ります。貴社はこのコードとクライアントシークレットを使用して、access_tokenとrefresh_tokenをHubSpotから取得することになります。

認証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

 

4.access_tokenを使用して、HubSpotアカウントに対して行うAPI呼び出しを認証します。

5.access_tokenの有効期限が切れたら、ステップ2のrefresh_tokenを使用して新しいaccess_tokenを生成します。


注:最初の2つのステップを完了しない限り、アプリはユーザーの連携設定で接続されたアプリとして表示されません。アプリが「接続済み」として表示されるには、リフレッシュトークンと初回アクセストークンを生成することが必要です。


クエリーパラメーター

このパラメーターは、アプリの認証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アカウント上の特定のツールへのアクセスを許可できるようになります。 

Screen Shot 2020-03-26 at 4.21.46 PM

特定のAPIまたはエンドポイントへのアクセスは、HubSpotアカウントのティアによって異なります。下記の表に、利用可能なスコープとアクセス可能なエンドポイントの完全なリストを示します。タイプが異なるHubSpotアカウント上で機能するアプリの場合は、optional_scopeパラメーターを使用して、使用する任意のティアスコープを含めることができます。これにより、すべてのスコープにアクセスできないCRMのみのアカウントを使用している顧客も、アプリを認証できるようになります。認証されていないすべてのスコープについては、アプリ側で確認および処理する必要があります。

 

すべてのスコープ
スコープ 説明 提供するアクセス先 必須アカウントティア
automation これにはワークフローが含まれます。 自動化API(ワークフローエンドポイント) Marketing Hub ProfessionalまたはEnterprise
business-intelligence これにはソースとEメールに関するエンドポイントが含まれます。 アナリティクスAPI すべてのアカウント
contacts これにはコンタクトとリストが含まれます。 コンタクト、会社、取引、プロパティー、エンゲージメント、担当者のエンドポイント すべてのアカウント
content これにはサイト、ランディングページ、CTA、Eメール、ブログ、キャンペーンが含まれます。 CMS API、およびカレンダー、Eメール、Eメールイベントのエンドポイント CMS Hub ProfessionalまたはEnterprise、またはMarketing Hub ProfessionalまたはEnterprise
crm.import レコードをCRMにインポート可能にします。これには、すべてのタイプのCRMデータ(コンタクト、会社、取引、チケットなど)の新しいレコードの作成、または既存のレコードの変更が含まれます。データのアーカイブや削除は含まれません。 CRMインポートAPI すべてのアカウント
e-commerce eコマース機能へのアクセス権が含まれます。 製品と明細のエンドポイント Sales Hub ProfessionalまたはEnterprise

注:このスコープを認証するには、ユーザーに有料のSales Hubシートが割り当てられている必要があります。
files ファイルマネージャーへのアクセス権が含まれます。 ファイル(ファイルマネージャー)とファイルマッパー(CMSテンプレート、モジュール、レイアウト)のエンドポイント すべてのアカウント
forms フォームエンドポイントへのアクセス権が含まれます。 フォームエンドポイント

注:フォームアクセスにはcontactsスコープも必要です。
すべてのアカウント
forms-uploaded-files フォーム経由で送信されたファイルをダウンロードします。 フォーム送信エンドポイント経由でアップロードされたファイルの取得 すべてのアカウント
hubdb HubDBへのアクセス権が含まれます。 HubDBエンドポイント CMS Hub ProfessionalまたはEnterprise、あるいはウェブサイト追加機能を付けたMarketing Hub ProfessionalまたはEnterprise
integration-sync これによって公開される同期APIにより、ほとんどのCRMオブジェクトを同期できます。  eコマースブリッジAPI すべてのアカウント
oauth OAuthに必要な基本的なスコープ。   すべてのアカウント
sales-email-read コンタクトに送信された1対1Eメールのすべての詳細の読み取りアクセスを許可します。 エンゲージメントエンドポイント

注:Eメールエンゲージメントのコンテンツを取得するには、このスコープが必要です。詳細についてはエンゲージメントの概要を参照してください。
Sales Hub Free、Starter、Professional、またはEnterprise
social これにはソーシャル機能が含まれます。 ソーシャルメディアAPI Marketing Hub ProfessionalまたはEnterprise
tickets チケットへのアクセス権が含まれます。 チケットエンドポイント Service Hub Free、Starter、Professional、またはEnterprise
timeline HubSpot CRMレコードでカスタムイベントを管理するためのアクセス権を許可します。これにはレコードの作成または更新が含まれます。 タイムラインイベントのエンドポイント すべてのアカウント
transactional-email これにはトランザクションEメールとトランザクションEメールのエンドポイントが含まれます。 トランザクションEメールのエンドポイント トランザクションEメール追加機能を付けたMarketing Hub ProfessionalまたはEnterprise

 


関連ドキュメント

HubSpotでの認証方式

OAuthクイックスタートガイド

トークンの管理