OAuthの利用
OAuthはアプリをユーザーアカウントに接続するための安全な認証手段で、パスワードではなく認証トークンが使用されます。ユーザーが自分のHubSpotアカウント上にアプリをインストール(英語)することを許可するためには、まずOAuthのアクセスを開始します。
注:複数のHubSpotアカウントによるインストール用に設計されたアプリ、またはアプリマーケットプレイスに掲載されるアプリでは、OAuthを使用する必要があります。
参考資料
- 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=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またはEnterprise、Marketing 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またはEnterprise、Marketing 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 |