Enhancing User Insights in Public Apps Using OAuth Tokens

Understanding who is using your app and how they are using it is crucial for improving user experience and driving engagement. By leveraging OAuth tokens with public apps, you can gather valuable user data. HubSpot offers an OAuth API and User Provisioning API that can help you achieve this. Here’s a detailed guide on how to use these APIs to gain insights into your app users!

What is OAuth, and how is it used with public apps?

OAuth2.0, a widely adopted industry-standard protocol, offers a streamlined and secure way to authenticate users. By leveraging OAuth2.0, developers can create a seamless sign-in experience with their app while safeguarding user information. But how does it do this? Let’s highlight the steps in which OAuth2.0 provides authentication below:

• Step 1: Authorization request
  • The application requests authorization from the user.
• Step 2: Authorization grant
  • The user grants authorization to the application.
• Step 3: Authorization code
  • The service provides an authorization code to the application. This grant type is commonly used for server-side applications.
• Step 4: Access token request (and refresh token request)
  • The application sends a request to the service provider’s token endpoint, exchanging the authorization code for an access token. In this request, the application includes the authorization code, client credentials (client ID and secret), and the redirect URI.
• Step 5: Access token and refresh token response
  • The service provides an access token and a refresh token. The access token is used for making the authenticated API requests, while the refresh token is used to obtain a new access token when the original access token expires.
• Step 6: Access resources
  • The application uses the access token to access the user’s account and interact with the protected resources on the user's behalf.

Note: The use of refresh tokens depends on the type of OAuth flow and the application's specific requirements.

With a HubSpot app, when a user decides to install your public app leveraging OAuth2.0, the following process takes place:

• User Installation: The user installs your app from the HubSpot App Marketplace or through a direct link to your app’s installation page.
• Authentication via OAuth: When installing the app, the user will be asked to grant specific permissions (also known as scopes) to access their HubSpot data. This is achieved using the OAuth protocol, which guarantees secure and regulated access. Tokens can be restricted to particular scopes, allowing only the essential permissions the app requires.
• Token Generation: Once the user authorizes your app, HubSpot generates an OAuth access token and a refresh token. These tokens allow your app to make API calls to the user’s HubSpot account without needing the user’s credentials.

Below is a demonstration of the OAuth authentication workflow when an end user installs a public app.

With the OAuth access token, your app can interact with HubSpot APIs to perform various actions on behalf of the user. For example, you can retrieve contact information, update CRM records, manage marketing campaigns, and access detailed analytics. The access token has a limited lifespan, but you can use the refresh token to obtain a new access token when needed, ensuring continuous access. It’s also highly recommended to include user scopes to identify your users who leverage your app tokens to gather their information when creating your app. We’ll clarify those specific scopes below when utilizing the different Users APIs.

Understanding HubSpot’s User’s APIs

HubSpot offers two distinct APIs for managing and retrieving user information: the User Provisioning API and the User Details API. Understanding their differences and specific use cases can help you effectively manage user data within HubSpot and know which to use with the OAuth API to gather user information from those users leveraging your application.

The User Details API is used similarly to our CRM objects. It is primarily used for retrieving user information like job titles, working hours, and other properties. When specifying users with the User Details API, you can leverage an ID to support batch operations and search with filters. It’s also important to note that the scopes differ between the two APIs. The User Details API requires the crm.objects.users.read scope, whereas the the User Provisioning API requires the settings.users.read scope.

The User Provisioning API is meant to create and manage users in an account and set their permissions. But, most importantly, you can leverage this API to specify a user by their ID or email in the API requests. By default, the user's ID is used. If you want to use the user's email, you would simply add the query parameter idProperty=EMAIL. Here’s an example:

https://api.hubspot.com/settings/v3/users/myUser@gmail.com?idProperty=EMAIL

This idProperty query parameter can be used in any endpoint that accepts userId as a path parameter. Below we’ll explain how to use both the User Provisioning API and OAuth API to gather the user information you’re seeking!

Retrieving user data

To retrieve user data, you can leverage the user ID with the OAuth tokens from the OAuth API. When using the OAuth API, you’ll focus on two endpoints that inspect the OAuth access and refresh tokens generated during the OAuth install flow that users use to authenticate with your app. Those endpoints are:

GET /oauth/v1/access-tokens/{token}

and

GET /oauth/v1/refresh-tokens/{token}

These two endpoints return important information with the following fields:

• user_id: HubSpot user who installed the app
• hub_id: HubSpot account ID the app is installed in
• user: Email address of the user who installed the app
• scopes: Approved scopes/permissions associated with the account/token
• hub_domain: Domain associated with the connected HubSpot account
• client_id: From the app that generated the OAuth token for the account
• token_type: Identifying if the token is a refresh or an access token
• expires_in: Token’s lifetime in seconds

Here’s an example of a response using Postman to make a request to the refresh-tokens endpoint, providing the refresh token value:

https://api.hubapi.com/oauth/v1/refresh-tokens/:token

Now that you’ve obtained the user_id from the refresh-tokens endpoint demonstrated above, use the User Provisioning API to fetch detailed user data using the user ID or the user’s email address. Here’s an example using the user ID from the refresh-tokens response:

https://api.hubapi.com/settings/v3/users/{userId}

The users endpoint then provides important user data such as a user’s email, first name, last name, user ID, etc. For more information, refer to the response schema here.

After using the OAuth and User Provisioning APIs to collect user data, it's a good idea to map some or all of the following OAuth token data points in your integration or token storage codebase. This practice will help you identify customers and provide details about the connected account for each OAuth access and refresh token generated. Overall, it enhances your ability to manage and use user information effectively!

Conclusion

Now that you are a pro at pulling user data for your app, you can gain valuable insights into who is using it by leveraging OAuth tokens with public apps. The combination of HubSpot's OAuth API and User Provisioning API allows you to securely access user information and tailor your services to meet their needs. This not only enhances the user experience but also provides you with the data necessary to drive engagement and improve your app's functionality.

Understanding your users better through these APIs can lead to more informed decisions, personalized interactions, and, ultimately, a more successful app. So, dive into this Postman collection today, and unlock your app's full potential for user insights!