In a world where data security is the top priority (or should be), OAuth 2.0 is your best friend. No more shared passwords or “one again” access that puts your users at the mercy of hacking. With OAuth 2.0, you add a layer of security, while making life easier for everyone. And that’s classy.
Why is OAuth 2.0 essential for HubSpot?
Quick reminder before we begin: HubSpot has said goodbye to API keys in 2022. And frankly, that’s good. For what ? Because OAuth 2.0 is safer, more flexible and (a little) less annoying to manage. But be careful, it’s not a walk in the park either. We're talking about protocols, tokens, scopes... in short, enough to make you sweat a little.
Concretely, OAuth 2.0 allows your application to request access to a HubSpot user's data without the user having to share their password. Basically, your app says to HubSpot, “Hey, can I come in?” And HubSpot says, “OK, but just for what you asked.”
Understand the basics of OAuth 2.0 (without drowning in jargon)
Well, we know that the terms "token", "client", "server" and "scope" are not very appealing. But we're going to try to make it cool. Here are the key elements:
- The customer : It’s you (or rather your application). You are the one requesting access.
- The authorization server : He’s the nightclub security guard. If you don't have the right documents (client ID, secret client), he leaves you outside.
- The access token : This is your entry ticket. But be careful, it expires after a certain time (usually 30 minutes).
- The refresh token : The VIP ticket. It allows you to extend the evening without having to wait in line again.
Step 1: Set up your HubSpot app
Before embarking on implementation, you must prepare the ground. Meet in your HubSpot developer account, and follow the guide:
- Create a new application. Give it a nice name, like “My Ultra Secure App” (it always sounds professional).
- Define your scopes. Scopes are what your application is allowed to do. For example:
- Read contacts (crm.objects.contacts.read)
- Edit properties (crm.objects.contacts.write).
- Configure the redirect URL. This is where the user will be sent after authorizing your application. It absolutely must be HTTPS if you are in production.
Once this configuration is completed, you will get a client ID and a client secret. Keep them carefully. (No, really, don't leave them lying around in a text file called "password.txt".)
Step 2: Create the Authorization URL
Now is the time to direct your users to the magic URL where they will give their consent. Here is an example:
https://app.hubspot.com/oauth/authorize ?client_id=VOTRE_CLIENT_ID &scope=crm.objects.contacts.read &redirect_uri=https://monappli.com/callback
And if you want to be a little flashier, add a setting state. It’s like a little note to yourself to know where the user is coming from.
Step 3: Obtain the famous access token
Now that your user has said "OK", HubSpot sends you a authorization code via the redirect URL. This code is the key to obtaining a access token.
How to do it?
Send a POST request to HubSpot with all the correct parameters:
POST https://api.hubapi.com/oauth/v1/token Content-Type: application/x-www-form-urlencoded client_id=VOTRE_CLIENT_ID client_secret=VOTRE_CLIENT_SECRET grant_type=authorization_code redirect_uri=https://monappli.com/callback code=LE_CODE
If all goes well, you will receive a response like this:
{ "access_token": "JETON_ACCESS", "refresh_token": "JETON_ACTUALISATION", "expires_in": 1800 }
Step 4: Use the access token
With the access token, you can finally start sending queries to HubSpot. But be careful, this is not an unlimited pass. The scopes defined at the outset must be respected.
Example API request:
GET https://api.hubapi.com/contacts/v1/lists/all/contacts/all Authorization: Bearer JETON_ACCESS
And there you have it, you have access to the requested data!
Step 5: Renew the access token (because it expires quickly)
The access tokens are like milk: they have an expiration date. Typically 30 minutes. Fortunately, thanks to refresh token, you can get a new one without annoying the user.
Example request to renew the token:
POST https://api.hubapi.com/oauth/v1/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token client_id=VOTRE_CLIENT_ID client_secret=VOTRE_CLIENT_SECRET refresh_token=JETON_ACTUALISATION
Pitfalls to avoid and good practices
- Never store the secret client in the clear. Use a secrets manager.
- Only ask for scopes you really need. Nobody likes apps that are too nosy.
- Handle errors properly. If the token expires, explain this clearly to the user.
What if something goes wrong?
- “Invalid redirect URI” error : Verify that the URL matches exactly what you configured in HubSpot.
- “Insufficient scopes” error : Make sure that the requested scopes match those defined.
- Expired token : Renew it with the refresh token.
OAuth 2.0 is a mountain, but we are growing from it
OAuth 2.0 may seem intimidating, but it is an incredibly powerful tool for securing your integrations. Once mastered, it becomes second nature (like riding a bike, but without the skinned knees).
- OAuth 2.0 is a must for any connected application.
- Access tokens are temporary, but renewable.
- Security is an investment, not a luxury.
And if all this still seems too complex to you, contact if/else agency experts HubSpot. We love diving into technical challenges (and yes, even those that involve tons of tokens and scopes).
