最終更新日: 2025年8月28日
OAuthはアプリをユーザーアカウントに接続するための安全な認証手段で、パスワードではなく認証トークンが使用されます。ユーザーが自分のHubSpotアカウントにアプリをインストールできるようにするには、まず、OAuthの使用を開始します。
注：
- 複数のHubSpotアカウントによるインストール用に設計されたアプリ、またはアプリマーケットプレイスに掲載されるアプリでは、OAuthを使用する必要があります。
- HubSpotアカウントでアプリをインストールするユーザーには、スーパー管理者の権限、またはアプリマーケットプレイスのアクセス権限が付与されている必要があります。
参考資料
- OAuthクイックスタートガイドで紹介されているサンプルアプリは、OAuthの利用をできるだけ短時間で開始することを意図して設計されており、全ての手順を実際にご利用いただけます。
- HubSpotアカデミーのコースでは、HubSpotでOAuthを使い始める方法を短時間で習得できます。HubSpot-OAuthフローの詳細や、アクセストークンの更新方法を説明しています。
OAuth認証の設定
アプリのOAuth認証を設定するには、次の手順に従います。- まず、HubSpot開発者アカウントでアプリを作成します。アプリを作成すると、アプリ設定の［認証］ページで作成したアプリのクライアントIDとクライアントシークレットを確認できるようになります。_ _
- 下記のように、クライアントIDとクライアントシークレット、およびクエリーパラメーターとスコープを使用して、認証URLを作成します。
-
アプリをインストールするユーザーを認証URLに誘導し、ユーザーがアカウントを選択する画面を表示して、連携機能へのアクセスを許可できるようにします。以下に示すように、
/oauth/と/authorizeの間にアカウントIDを追加することで、特定のHubSpotアカウント用の認証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/ - 特定のアカウント（ID 123456）:
https://app.hubspot.com/oauth/123456/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
- 任意のアカウント:
- リダイレクトURLの例:
https://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を作成する際には、以下のクエリーパラメーターが必須です。| パラメーター | 説明 | 使い方 |
|---|---|---|
client_id | アプリの固有IDとして機能するID。 | アプリの認証設定ページから（上記の説明に従って）取得します。 |
redirect_uri | 訪問者がアプリへのアクセス権を取得した後にリダイレクトされる宛先URL。 | アプリの認証設定ページでも、このURLを指定します**。注**: セキュリティー上の理由により、本番環境ではこのURLにhttpsを使用する必要があります（localhostを使用したテスト環境では、httpを使用することも可能です）。また、IPアドレスはサポートされていないため、必ずドメインを使用してください。 |
scope | アプリに対する権限セット（権限ごとにスペースで区切ります）。 | アプリの認証設定でチェックマークを付けたスコープは必須と見なされるため、このパラメーターに含めない場合は認証ページにエラーが表示されます。_ _また、ここに含まれたスコープへのアクセス権がないアカウント上にアプリをインストールしようとした場合、エラーが発生します。特定のスコープでアクセスできるエンドポイントの詳細については、スコープに関するリファレンスドキュメントをご参照ください。 |
| パラメーター | 使い方 | 説明 |
|---|---|---|
optional_scope | 貴社のアプリに対する任意アクセス許可（許可ごとにスペースで区切ります）。 | ユーザーがそのツールへのアクセス権を持っていないHubSpotアカウントを選択した場合（HubSpotの無料アカウントでContent Hub Enterpriseスコープを承認する場合など）、任意指定のスコープは自動的に認証リクエストから除かれます。_ _任意指定のスコープを使用する場合、許可されたスコープを把握するためにはアクセストークンまたはリフレッシュトークンを確認する必要があります。詳細についてはスコープに関するリファレンスドキュメントをご覧ください。 |
state | 認証URLにこのパラメーターを含めた場合、ユーザーがredirect_uriに誘導される際に、ここで指定した値が状態クエリーパラメーターに格納されます。 | リダイレクトされてアプリに戻ってきたユーザーの状態を維持するために使用できる文字列値。 |
スコープの設定
OAuthでは、アプリに対するスコープ（権限）を設定する必要があります。各スコープによって、一連のHubSpot APIエンドポイントへのアクセス権が与えられます。また、アプリによるHubSpotアカウント上の特定のツールへのアクセスを、ユーザーが許可できるようになります。
optional_scopeパラメーターを使用して、対応するあらゆるティアのスコープを含めることができます。これにより、HubSpotの無料アカウントを使用しているお客さまも、全てのスコープにはアクセスできなくても、アプリを認証できるようになります。認証されていない全てのスコープについては、アプリ側で確認および処理する必要があります。
スコープの完全なリストはこちらのページで確認できます。