最終更新日: 2025年8月22日
OAuthトークンAPIを使用して、公開アプリの認証、および公開アプリからのリクエストの認証に必要なトークンを生成し、管理します。例えば、アプリのインストールプロセス中に、このAPIを使用して初回アクセストークンとリフレッシュトークンを取得する必要があります。その後も引き続きこれを使用して、古いトークンが期限切れになったときに新しいトークンを生成します。詳しくは、OAuthの利用をご確認ください。 これらのエンドポイントを使用するには、その前に公開アプリを作成する必要があります。その後、ユーザーがそれを自分のアカウントにインストールして、OAuthアクセスを開始する必要があります。

OAuthアクセスの開始

アプリを作成した後、ユーザーはアプリの設定にあるインストールURL(クエリーパラメーターとしてclient_idredirect_uriscopesを含む)を使用して、アプリを自分のHubSpotアカウントにインストールできます。また、必要に応じてoptional_scopesおよびstateを含めることもできます。 ユーザーがアプリを認証してアカウントにインストールした後、リダイレクトURLにcode値が付加されます。これを使用してアクセストークンとリフレッシュトークンを生成できます。アクセストークンはアプリが発行するリクエストを認証するのに使用され、リフレッシュトークンは現在のアクセストークンが期限切れになったときに新しいものを取得するために使用されます。 詳しくは、アプリでOAuthを開始する方法をご確認ください。

初期アクセストークンとリフレッシュトークンを生成する

OAuthのアクセストークンとリフレッシュトークンを取得するには、URL形式でエンコードしたPOSTリクエストを/oauth/v1/tokenに送信します。リクエスト本文では、client_idclient_secretなどのさまざまな認証パラメーターと、リダイレクトURLを通して返されるcodeを指定します。 ユーザーがアプリを認証した後、リダイレクトURLにcode値が付加されます。このコードを使用して、初期アクセストークンとリフレッシュトークンを生成します。アクセストークンの存続期間は短時間です。アクセストークンの生成時にexpires_inパラメーターを調べると、存続期間(秒数)を確認できます。 例えば、リクエストは次のようになります。
curl --request POST \
  --url https://api.hubapi.com/oauth/v1/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&code=bcf33c57-dd7a-c7eb-4179-9241-e01bd&redirect_uri=https://www.domain.com/redirect&client_id=7933b042-0952-4e7d-a327dab-3dc&client_secret=7a572d8a-69bf-44c6-9a34-416aad3ad5'
パラメーター説明
grant_type文字列リクエストで初期アクセストークンとリフレッシュトークンを生成するには、authorization_codeでなければなりません。
code文字列ユーザーがアプリをインストールした後にリダイレクトURLで返されるcode
redirect_uri文字列アプリで設定されたリダイレクトURL。
client_id文字列アプリのクライアントID。
client_secret文字列アプリのクライアントシークレット。
レスポンスの中でアクセストークンを受け取り、さらにアクセストークンの更新に使用できるリフレッシュトークンも受け取ります。expires_inフィールドは、アクセストークンの有効期間(秒)を指定します。
{
  "token_type": "bearer",
  "refresh_token": "1e8fbfb1-8e96-4826-8b8d-c8af73715",
  "access_token": "CIrToaiiMhIHAAEAQAAAARiO1ooBIOP0sgEokuLtAEaOaTFnToZ3VjUbtl46MAAAAEAAAAAgAAAAAAAAAAAACAAAAAAAOABAAAAAAAAAAAAAAAQAkIUVrptEzQ4hQHP89Eoahkq-p7dVIAWgBgAA",
  "expires_in": 1800
}

アクセストークンの更新

リフレッシュトークンを使用すると、URL形式でエンコードしたPOSTリクエストを/oauth/v1/tokenに送信することで、新しいアクセストークンを生成できます。リクエスト本文でgrant_typeclient_idclient_secretrefresh_tokenを指定します。
curl --request POST \
  --url https://api.hubapi.com/oauth/v1/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token&refresh_token=1e8fbfb1-8e96-4826-8b8d-c8af73715&client_id=7933b042-0952-4e7d-a327dab-3dc&client_secret=7a572d8a-69bf-44c6-9a34-416aad3ad5'
パラメーター説明
grant_type文字列リクエストでリフレッシュトークンから新しいアクセストークンを生成するには、refresh_tokenでなければなりません。
refresh_token文字列リフレッシュトークンの値。
client_id文字列アプリのクライアントID。
client_secret文字列アプリのクライアントシークレット。

アクセストークンのメタデータを取得する

OAuthアクセストークンに関する情報(トークン作成の対象となったユーザー、および対応するHub IDなど)を取得するには、GETリクエストを/oauth/v1/access-tokens/{token}に送信します。 ユーザーのアクセストークンとそのHubSpotアカウントに関する情報を含むレスポンスが届きます。
{
  "token": "CNaKSIHAAEAQAAAARiO1ooBIOP0sgEokuLtATIU5m7Kzmjj0ihJJuKFq1TcIiHCqwE6MAAAAEEAAAAAAAAAAgAIUfmerBenQwc07ZHXy6atYNNW8XCVKA25hMVIAWgBgAA",
  "user": "user@domain.com",
  "hub_domain": "meowmix.com",
  "scopes": [
    "oauth",
    "crm.objects.contacts.read",
    "crm.objects.contacts.write"
  ],
  "signed_access_token": {
    "expiresAt": 1727190403926,
    "scopes": "AAEAAAAQ==",
    "hubId": 1234567,
    "userId": 293199,
    "appId": 111111,
    "signature": "5m7ihJJuKFq1TcIiHCqwE=",
    "scopeToScopeGroupPks": "AAAAQAAAAAAAAAACAAAAAAAAAAAAAIAAAAAAA4AEAAAAAAAAAAAAAABAC",
    "newSignature": "fme07ZHXy6atYNNW8XCU=",
    "hublet": "na1",
    "trialScopes": "",
    "trialScopeToScopeGroupPks": "",
    "isUserLevel": false
  },
  "hub_id": 1234567,
  "app_id": 111111,
  "expires_in": 1754,
  "user_id": 293199,
  "token_type": "access"
}

注:

HubSpotアクセストークンにエンコードされる情報は更新されていくので、時間の経過とともにトークンのサイズが変動することが予想されます。あらゆる変更に対応できるよう、トークンサイズには最大512文字分を確保することをお勧めします。

リフレッシュトークンの削除

ユーザーがアプリをアンインストールした場合は、DELETEリクエストを/oauth/v1/refresh-tokens/{token}に送信してリフレッシュトークンを削除できます。この処理で削除されるのはリフレッシュトークンのみです。リフレッシュトークンを使って生成されたアクセストークンは、削除されません。また、これによってHubSpotアカウントからアプリケーションがアンインストールされたり、アプリとアカウントの間のデータ同期が妨げられたりすることはありません。