Initiating an OAuth Integration

GET /auth/authenticate

Method Details

HTTP Methods:

GET

Response Format:

OAuth Access Page

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Both

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.

  1. Start by creating an app in your developer account. You will be provisioned a Client ID to be used here.
  2. Now that you've registered your application, you will use the HubSpot OAuth authorization screen to get user authorization to their data in HubSpot, and get access tokens which will get you access to the user's data in HubSpot. To get an access token from an external app, you need to send the user to HubSpot OAuth Access Page, at this URL: https://app.hubspot.com/auth/authenticate/

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:

  • If the user accepts your access request on the OAuth Access Page, a valid access_token, expires_in time in seconds and a refresh_token (if offline scope is present) will be appended to the URL the user will be re-directed to. If a refresh token is present, you'll store that token and use it to periodically refresh for a valid access token.
  • If the user rejects your access request, or an error occurs, a redirect (still 302) will be issued with an error parameter and a short error message.
  • If the scope parameter was included in request it will also be included as a parameter in the response.