OAuthの利用
OAuthは、アプリをユーザーアカウントに接続するためにパスワードではなく認証トークンを使用するセキュリティーで保護された認証手段です。OAuthのアクセスを開始することは、ユーザーが自分のHubSpotアカウント上にアプリをインストール(英語)できるようにするための最初のステップです。
注:複数のHubSpotアカウントによるインストール用に設計されたアプリ、またはアプリマーケットプレイスに掲載されるアプリでは、OAuthを使用する必要があります。APIキーを使用している場合、アプリ掲載は却下されます。
お勧めの参考資料
- OAuthクイックスタートガイドでは実際に動くサンプルアプリを使って作業に慣れていただけます。
- HubSpotアカデミーチュートリアル(英語)はHubSpotでOAuthを短時間で使い始めるための導入資料です。HubSpot-OAuthフローの詳細や、アクセストークンの更新方法が記載されています。
OAuth 2.0との連携を開始する
1. OAuthを使用するための最初のステップは、HubSpot開発者アカウントでアプリを作成することです。これにより、アプリ設定の認証ページでアプリのクライアントIDとクライアントシークレットを確認できるようになります。
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
の有効期限が切れたら、ステップ3の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アカウント上の特定のツールへのアクセスを許可できるようになります。
特定のAPIまたはエンドポイントへのアクセスは、HubSpotアカウントのティアによって異なります。下記の表に、利用可能なスコープとアクセス可能なエンドポイントの完全なリストを示します。タイプが異なるHubSpotアカウント上で機能するアプリの場合は、optional_scope
パラメーターを使用して、使用する任意のティアスコープを含めることができます。これにより、全てのスコープにアクセスできないCRMのみのアカウントを使用している顧客も、アプリを認証できるようになります。認証されていない全てのスコープについては、アプリ側で確認および処理する必要があります。
注:一部のHubSpot APIは、以下の表の標準スコープに加えて、きめ細かいスコープ(crm.objects.contacts.read
など)に対応しています。きめ細かいスコープに対応するエンドポイントでは、標準スコープが「レガシースコープ」と示されますが、特に明記されている場合を除いてレガシースコープも引き続きリクエストで使用できます。
スコープ | 説明 | 提供するアクセス先 | 必須アカウントティア |
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 |
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またはEnterprise、またはMarketing Hub ProfessionalまたはEnterprise |
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オブジェクトを同期できます。 | Ecommerce Bridge(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 |