Note: This version of OAuth is deprecated.
Please Use OAuth 2.0.
The following steps walk you through initiating an OAuth handshake on behalf of a user of your integration. The current implementation of OAuth does not follow a strict OAuth v1 or v2 spec, but the initial handshake is straightforward.
In the request, you must pass along the following information as parameters in the URL, which we will use to redirect your user and authorize your app, passing back a new access token, along with a refresh token to use to refresh the access token later. Here are the parameters to pass to the OAuth Access page URL:
|Required Parameters||How to use||Description|
|Client ID||client_id=XXX - Used in the query string||Your client ID is unique to your app and is generated when you first register your app in the developer portal. You can view your app's client by logging into your developer account.|
|Hub ID||portalId=XXX - Used in the query string||The HubSpot portal ID of the customer that you're re-directing. You will need to get the portal ID from the customer who you're making the request for - it can be found in the upper righthand corner of the HubSpot application.|
|Redirect URI||redirect_uri=XXX - Used in the query string||A redirect_uri where you want to send the user after they accept or reject your request for access on the OAuth access page. There is a limit of 1024 characters for the redirect uri length.|
|Scopes||scope=XXX+XXX - Used in the query string||The scopes (or permissions) you want your users to grant you. Separate more than one scope with "+" in your URL request. A full list of the scopes that you can request is below.|
You'll request scopes in order to a) alert the user as to what data you can access or modify and b) to define whether your application will need to refresh the users authentication programmatically.
|Scope||How to use||Description|
|Offline Access||offline||This application can make API requests on behalf of the user when the user is offline (not actively using the app). You will receive a refresh token when the user authenticates that you can store to gain access to a new, valid access token programtically using the refresh token method.|
|Contacts Read/Write||contacts-rw||This application reads your contact information, as well as creates new contacts, contact lists, and contact properties. It can also modify existing contacts, properties, and contact lists.|
|Contacts Read-Only||contacts-ro||This application can read your contact information, as well as information about your contact properties and contact lists.|
|Blog Read/Write||blog-rw||This application can read your blog data, including posts and comments, as well as create new blog posts and comments.|
|Blog Read-Only||blog-ro||This application can read your blog data, including posts and comments.|
|Events Read/Write||events-rw||This application can read your marketing events, as well as post new ones into your HubSpot account.|
|Keywords Read/Write||keyword-rw||This application can read your keyword data, as well as insert new ones into your HubSpot account.|
If you don't see a scope that you were expecting here (for example a form-rw scope for the Forms API), it's because we haven't created that scope yet! You'll still be able to access the data for those APIs not listed above without a scope.
An example successful request might look like: https://app.hubspot.com/auth/authenticate?client_id=4a9c6e70-eb7a-11e3-9f41-dd07f568fa92&portalId=62515&redirect_uri=http://developers.hubspot.com&scope=offline
Our response will be a 302 redirect to the "redirect_uri" that you provide in your request. We'll also include various parameters depending on the user's action: