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