Postman OAuth with Carter McKay of PivIT Global

Hey everybody. Recently I was having a conversation with Carter here, who you see next to me, Carter McKay, lead developer at Pivot Global. We were talking about a lot of questions we've been seeing in our developer Slack lately. And I see him in the developer forums as well. And that is all things OAuth. So I said, carter, let's do something about that. Let's have make a little video here and let's just walk through what OAuth is. Maybe we'll set something up on Postman just so you can test, you know, your, your, your situation. And after that I thought, you know what? Bonus, let's do us a lightning round of common OAuth errors people receive in the questions, how to resolve them. Just want to indicate, yes, we are going to do a Postman demo, but if you want to do a more this is not production. Right. This is for testing purposes. We have a, a blog post up and I'll send a link to that as well. From Tim Joyce on doing OAuth with I think Laravel is what he used. But anyway. Hey Carter.

Hi.

I talked a lot now and how are you doing?

Doing great. Doing great. Yeah. Just like you mentioned, like, it's postman. OAuth, like a lot of apps that people are building these days do not need a full production setup. Like a couple examples are like webhooks, like you don't ever need access to like other accounts. If APIs in HubSpot or webhooks or like CRM cards, you might not necessarily need access and a couple other different versions of that. But HubSpot made it a requirement for every app to be installed to request at least one OAuth token. And now because of that requirement, a lot of people that don't necessarily need full OAuth setups are a little bit stuck where they might not have the skills to set up a full OAuth environment, but they just want to install that one app to set up webhooks, for example, on one account. So this is.

And if you're listening at home right now, you might just heard one of our lightning round questions just answered. So if you're paying attention, you should already know one of the answers. Okay, cool, Carter, just first of all, let's back up and explain just oauth what it is and why you need it. And if you don't mind, would you actually just talk about. Because we have two different ways of authenticating private apps and OAuth, would you just go through use cases for each?

Yeah. So OAuth is basically the way that public apps, public HubSpot apps authenticate with a HubSpot portal. And so like say you have a app, for example, that you want to install on multiple portals. Maybe you're trying to make money from this app. You'll want to use OAuth so that you can get information from someone's HubSpot portal and pull it back into your systems or push information from your systems in HubSpot. The if you are just trying to build an app just for your one company and your one portal, you're going to use a private app. They both use OAuth, which is like this authentication method. But HubSpot public apps use an OAuth method that's a little different, that uses. It's called OAuth 2.0 and it's a little more in depth.

Would you mind just walking quickly through the process of this OAuth 2.0 and how HubSpot deploys it or employs it?

Yeah, yeah. So basically HubSpot, it's, it's a pretty simple process. You set up your app on a developer account, you request all of your scopes. So the, the scopes you're going to be using, pretty simple. You got like context, read and write. They're, they're very granular. So you just double check to make sure, oh, these are the scopes I'm going to use for this app. You also try and future proof those scopes a little bit in your head and request the scopes that you want to request. Then you copy over all of your client ID and client secret into Postman, like we'll show in a minute here. And then you'll use a link, everyone can use the same link to install that app on a HubSpot portal. And then once that app is installed, it'll ping your server and say, hey, you just got an app installed. And then you can start on using that app in the.

Okay, and starting APIs you mentioned scopes. Would you just go ahead and just what are scopes? Why do I care about them at all?

Yeah, so both private apps and public apps use scopes. Scopes basically say, hey, my app will only ever touch the contacts part of HubSpot. Or this, this particular private app is only ever going to touch the deals part of HubSpot. It, it's basically a granular way to say, like to implement security and also just like protecting part of your HubSpot account, you never really want to install an app where someone could have the entire access to your entire HubSpot account. No one ever should have access to that. So scopes are just a way to say, hey, you only get access to this, or you only get access to that.

Now, if you don't mind, I want to dig a little bit deeper on scopes real quickly. Not all subscription types have access to the same scopes, but if I'm building a public app, how do I target each different type? Subscription type. So I do want to do something really special like on an enterprise account, but obviously a starter account doesn't have that. How do I go about that?

Yeah, yeah, so that's a very common issue. So basically, like, let's. Let's use. Let's use GraphQL for example. GraphQL is something that CMS Pro and Enterprise accounts have access to. But if you don't have CMS Pro and Enterprise, you won't have access to GraphQL. GraphQL has a scope in HubSpot, though, and so for your app to use GraphQL on those accounts types, it needs that scope. But if you try and install that app with a GraphQL scope on an account that does not have access to GraphQL, it will fail. So the way you have to do that is you have to use the optional scopes parameter in HubSpot, and we'll link to the doc for that exact thing. But it's just a very simple optional scopes instead of scopes. You'll pop in that GraphQL in there instead, and that's the way it'll. Your app will still install on apps that don't have GraphQL, and it will install on apps that do, on accounts that do have GraphQL, but only the accounts that do have access to GraphQL. Will you be able to use that token with the GraphQL API?

Yeah.

Perfect.

And as I'm installing an app, I get to see, basically me, the person who's installed, I get to see a list of things that this app is requesting. Yeah, I get to approve it. We've all done this probably, like with Google and things like that before. Right. So it's pretty familiar process from an end user's point of view.

Exactly.

All right, let's get to the fun part. Postman Oauth showing everything. Carter.

Okay, let's see here. Okay, you're seeing my screen. All right, beautiful. Okay, so the first part of this is in your HubSpot developer account. Let's open that up really quick. I have built like a simple demo app here, and this simple demo App has basically two scopes. They have a contact read and a contact write. The second part of this and we go bottom to top. It's pretty, it's pretty simple that way. The second part of this is your redirect URL. If you are doing a more production version of OAuth, your redirect URL is going to be your server URL and not Yahoo.com like in my example. But because we're doing just a postman example, Yahoo.com is perfect for that. And then stop you on the part of this.

I'm sorry, Carter, I want to stop you real quickly on that redirect. Just for people going to the production way, that's also going to generate a code that one would use to actually initiate the authentication and get your refresh token and access tokens, right?

Yep, yep, exactly. So that redirect URL, it's in a. It's in a send a. It's going to send a little code to your server and it's going to say, hey, someone just installed the account. You're the app on an account. Here's that code. You're then going to need to switch that code into a token and then you can use that token for API calls exactly like that. But yeah, for, for our simple Postman version, you can pop in yahoo.com, google.com it doesn't really matter. And then the last part of this is just your client ID and your client secret. So basically these two are your most important parts. You definitely don't want to show anyone these two tokens here, but you will copy these two into your Postman setup. And we'll share the Postman request, the, in the description, but you'll pop it in under, under Client ID and client secret. And then your scopes, you will pop in right under the scopes parameter with just a space separating them and we are good to go. Everything matches here. You just got to verify that everything matches. Some stuff doesn't match, that's totally fine. You, but the app will install and you will get an error code that says, hey, something doesn't match. So I just thought it's really good about the errors, but you just got to make sure things match. And so the next step here is we just click get new access token. It's going to load up a simple frame here. We're going to click on the account we want to use, choose that account, and boom, it just installed Postman saying it's collecting a new access token. It got it. We're Going to click Proceed. We'll then click use this token and boom, it just copied that token into the authentication there. And we can do a simple contacts call right there. And so let's see where. Okay, look at that. It grabbed a couple of our contacts in HubSpot for that particular account.

I love it. All right, and as Carter mentioned, we'll have all kinds of links and stuff in the description, so you can replicate this and play around. But now, Carter, our last little section, the lightning round. Let me go ahead and pull up my questions here. I hope you're ready. Don't sweat, don't worry. This is not going to be too bad. Okay, question number one, Lightning round. This oauth token does not have proper permission. What's. What's happening there?

Yep, yep. And so that issue is when your scopes and postman or in your production setup do not match the scopes that you set up in your developer app settings, you got to make sure those two match, otherwise the app will install because you're saying, hey, I want all these scopes in your. Your account. Saying, hey, you only have access to these. And so if there's a Mitch, if there's a mismatch, you're going to get an error.

Cool. Next question. This app hasn't been granted all required scopes to make this call.

Yeah, similar. Yep, very similar. So basically this is actually even more of a problem if you. And it works the same way for private apps and public apps that that error. So if you request the contacts read and write scopes like we just did in that example, but then you try and go and call the company's endpoints, you're going to get that error. And that error says, hey, you only said you wanted context read and write. You never said anything about companies, so you don't have access to this. You got to put in the company scopes in your developer app settings and in your. And in your postman or production setup to get those actual things, but then say, so you have accidentally made that mistake. If you then want to go back through and add that scope right now, we could go into the developer app settings, add the company scope and then update it. You then have to reinstall the app because you can't. You can't say, for example, you have a mischievous app developer that decides, oh, I'm only going to tell people I'm going to use the contact scope. But then later says, oh, I want to use everything. Obviously that's a security risk, so you have to reinstall the app for those new scopes types to take place.

Carter, you just answered my third question I was going to ask. I'll allow it this one time, but don't let it happen again. I'm going to move on to number four then. This account doesn't have access to some HubSpot features that are required by this app.

Yep. So again, that's. That's the optional scopes thing. So say you're requesting the GraphQL feature, but you're not popping it into the optional scopes, and then you're installing it on an account that does not have CMS Pro or Enterprise. You're going to get that error. So any scopes that are. That are account specific, you're going to want to pop them into the optional scopes and we'll share that list of the account specific scopes. HubSpot has a really good developer documentation on it. It lays out all of the account specific scopes. But again, maybe this error is a good thing because Your app requires GraphQL and so you don't want people installing your app if they do not have GraphQL and so maybe that error is a good thing in a lot of cases.

Cool.

Cool.

All right, last question. And I alluded to this earlier. I installed my app on a test portal, but I do not see it in the connected apps. What gives?

Yeah, so HubSpot last June 2020 decided that all apps that are installing on accounts need to request one access token before the app actually gets installed. So even if you go through the full flow setup and you use the install URL, but you don't actually request an access token, it'll look like your app got installed and HubSpot will say from the little front end perspective that it got installed. But if you don't request that one access token, HubSpot's not actually going to install it. And so you can do the postman setup to get that one access token, or you can do the production version that we'll share to get that one access token. But as long as you get one access token, you won't have that problem. If you forget to do the access token, you will have to reinstall the app until you request it.

Got it. That's my lightning round. You did a good job. You aced the quiz. Carter, is there anything else that you can think of that we should make sure we mention? I just grabbed all those literally from our forums and our slack. Yeah, so I think I grabbed the main ones. But if there's anything else you can think of?

No, I mean, honestly, yeah, those are the. Those are the main ones. Like, a lot of people are building cool stuff with apps, but you. The main thing you got to remember is you got to be thinking ahead when you're scoping out your app. And you got to say, hey, like, while I only want contact scopes right now, in the future, I have this V2 version of my app and I don't want people to reinstall the app, so I might as well request the company's scopes while I'm building this app. That's something you got to think ahead about. You can't. You can't just proactively change the scopes and have those changes push.

Beautiful. Love it. Carter, thank you so much. As mentioned before a thousand times, everything's going to be in the description below. If you have questions, leave in the comments. You will see Carter all over the place on the developer slack. So if you do have questions, you want to talk to this guy. He's a very amazing guy.

Friendly. YouTube around for a while.

All right, have a good day. Bye. Bye.