How to use the JumpCloud API with Postman

How to use the JumpCloud API with Postman

Jump to the Video

If you're like me, or really any "work smart, not hard" type person, then you love automation. There is a rule that if you do something once, it's a task. If you have to do that thing frequently, it should become an automation. I don't know if that's a real rule, but it sounds good and I like it. But then there are other rules such as, "Automation isn’t a silver bullet, and it won’t fix your broken processes for you." At the end of the day, automation is great and fun, but it should be implemented on processes that already work in order to reduce the resource constraint of repetitive tasks.

That brings us to the next step. How do you go about automating? The good news, is that you don't need to be a mad scientist to accomplish this automation like Dr. Frankenstein! You can start small and simple and work your way up to bigger and better automatons.

Automation isn’t a silver bullet, and it won’t fix your broken processes for you.

JumpCloud API

The JumpCloud API is a RESTful API that allows for automation to to interface with all of your JumpCloud data within your organization. This allows you to create users, read user information, update user information and even delete. The same can be said for systems, user groups, directory integrations etc. Some would say, it's a Programming Interface for the JumpCloud Application 😏, see what I did there?

You can find all the documentation for the API here

Postman

Postman is an application that can be used in a web-browser or as a desktop application that is used for for API testing in a graphical interface. This tool allows you to directly interact with an API create points of concepts. This allows you to create collections and have different testing environments for multiple API endpoints.

Together, we will use the Postman application, to pull and update data into the JumpCloud API to create the foundation of future automation steps!

The Video

Transcript

[00:00:00] Ben: If you like me, you like automations and automations are fun to set up and they solve having to do mundane tasks all day long, but also automations help organizations grow and scale. But oftentimes people are hesitant to attempt automations because they feel it requires being some kind of mad scientists working in a lab all night, running experiments in reality, automations are very simple and depending on what you're trying to automate can be done in only a few hours leaving plenty of time to get coffee.

[00:00:26] Ben: That's usually the best way to automate is to leverage an application's API. This is typically something that you find very common in SAS based applications and cloud solutions. JumpCloud has a restful API that allows it admins to fully automate their directory of users, systems, user groups, and other resources.

[00:00:44] Ben: The documentation is pretty helpful, but just reading the documentation can sometimes be a bit well boring if you ask me, cause I don't like documentation as we all know. Unless you're really into API documentation. Hey, go for it. So what we're going to do is we're going to dive into how to use postman, which is an HTTP API testing tool to

[00:01:08] Ben: Help you leverage and interface with the JumpCloud API to get a list of users and also create a user using this application called postman. Now, before we begin, it is full disclosure that I am a JumpCloud full-time employee. I do post these videos on my own YouTube channel, as well as on other platforms.

[00:01:29] Ben: And sometimes even on the cloud YouTube channel. But this video is more so how to automate in general, we're just going to use JumpCloud as the end point that we're going to test against. So looking at the JumpCloud documentation, we can see that there are a couple of end points. There's the directory insights end point, the JumpCloud API version one and version two directory insights gives you a JSON

[00:01:58] Ben: object of all of the events that happen in your organization. So things such as looking here. Deleting a user updating users deleting or logging in basically all of the different events that you can imagine that can happen within your organization all happen here. And these are the events from the last hour.

[00:02:18] Ben: It gives you all of the data that you need. Going back into the documentation for our API, we're looking at the JumpCloud version one API, which is slightly different than the version two. And we'll, we'll talk about those differences here in a moment. So the version one is more along the lines of the objects of the top level pieces of your directory.

[00:02:41] Ben: So things such as devices, users, resources, authentication, right? Looking at things such as commands systems as well as system users. So let's look at the system users object for a second. So a couple of the end points that we're going to dive in today is list all system users. And then we're going to create a system user.

[00:03:00] Ben: We're also going to list a particular system user, but we're going to do it in a different way. So list all system users allows you to pull a list of, well, all of the users that were in your organization, you can default to a limit of 10, which I think is the default. You can this, I think this goes up to a hundred.

[00:03:17] Ben: You can put in there. You can also filter out the users by departments or by a filter field. If I look at the entire object here, I can filter out all of these different fields and look for a particular value. So for instance, if I wanted to grab the department and I wanted to look at a marketing department or accounting department, I can look at that and I can pull all the Le all the users that were in this department directly.

[00:03:46] Ben: Pretty neat in that respect. So simple, simple API stuff. If you already know an API, then you can go ahead and ignore the video altogether. But this is for people who want to get involved in this kind of stuff. And this is great because if you use postman to get a good understanding as to how the API end points work, then plugging them into other automation tools such as Zapier or I FTT or power automate.

[00:04:07] Ben: Those things become a lot easier because you already know what the headers look like. You know what it's asking for and you know how to move forward with that. Going back into the, the front page here looking at version 2.0, we know that the system users in point system user end point is all about the user object.

[00:04:26] Ben: So it gives you all the information regarding the user, or as the, see the user's end point over here on this documentation gives us the associations of the user, right? So what directories are bound to the user? What's the parent groups of the user, et cetera, et cetera. So it gives you a, a general idea and you might hear my daughter in the background playing with our puppy.

[00:04:53] Ben: So I apologize for that, but it's kind of cute. All right. So moving on, we're going to go back into our version one documentation. Cause what we're going to do today is we're going to look at how. Leverage the system users in point, this is a very basic rudimentary level introduction into this. We might get into some more advanced documentation or API stuff in the future, but for now we're just going to do our building blocks and then kind of go from there.

[00:05:21] Ben: So what we want to do is we want to look at this end point. We want to just basically get a good understanding as to what we're looking for. Right. So to filter a plot, to filter a filter, to apply the query you have your operators. So for complex searches, see the re the related search domain end points.

[00:05:38] Ben: Which we'll talk about at some point, but we'll looking at the, so we have a search here, but we have filter structure, right. Field operator value. These are going to be important when we start looking at how to get a list of users by marketing department. Okay. So now we want to do is we want to look at a user for a second here.

[00:05:54] Ben: We want to look at, for instance, we're going to look at John babble and we're just going to look to see the details here. So we have, you know, their first name, last name, email username, but we also have their password, et cetera. So we're going to look at their employment information and we're going to put them in the field of marketing.

[00:06:18] Ben: Save user. Okay. So we, now we have three users and we have, their passwords are ex expired, but that's fine. Whatever. We're not worried about that. These are all test users. They don't really, they don't really exist. Okay. So let's go ahead and go into postman real quick. And we're going to create, I already create a workspace to create a new workspace.

[00:06:35] Ben: You just come in here, you hit create workspace. I created a workspace called JumpCloud playground. And we have no API APIs yet. No collections. You can create an API collection by doing it manually. But what I like to do is just import, so the way we import, so we go over here to our JumpCloud version one, go to overview.

[00:06:55] Ben: It takes you to this header, scroll up a little bit. We're going to hit download, and this is where we download. That Yammel file, but we're going to hit the, we're going to hit the little import button here and we're going to upload files and here is the index dot Yammel it open. And we're going to bring this in as a collection hit import, and it's going to scrub that GMO file and it's going to create a.

[00:07:22] Ben: Collection of API end points that we're going to be able to easily leverage. All right. File structure is a little funky when it comes in. So it brings in his draft API. So here is your API collection for a jump cloud. The first thing we want to do is you want to set up some variables. So we're going to click on this little collection section here, and we're going to look at our variables.

[00:07:45] Ben: There are two variables that I wanted to find. There's already one that's set by default, which is the base URL. And that is the base URL for where your end points go. So basically console.jumpcloud.com for slash API slash system users is where we're going to be heading at because that's the end point, but we do need to other a variable.

[00:08:04] Ben: So we're going to set one for your X org. Right. And we're going to set one for your ex API key, right? And then what we're going to do is go and go into our admin panel here. And we're going to grab the organization ID you got by going into settings, grab the organization. ID, hit the little copy button here and go back in to there.

[00:08:28] Ben: And just paste that in API key. We're going to grab the API set. And we're going to generate new API key. Now, if you do this and you already have integration. You just broke all your integrations. I do it because this is a test environment and I just like having a new API key every time. Bam. All right, let me hit save.

[00:08:52] Ben: So now we have all these variables and we're going to see how that plays in here in a minute, makes it very easy to update things. So we're going to assist them users. Let's just get a list of all of our system users. So looking at a headers here, we have. The API key, which is coming from the authorization tab.

[00:09:08] Ben: We'll get there in a second, but then we also have our X org ID. We already defined a variable in the collection level. So you just do two open brackets and you're able to grab the XRD easy peasy, lemon squeezy as right. And then authorization. We're going to come in here and we're going to do again.

[00:09:25] Ben: We're going to grab the X API. Okay. All right. So if you look at the call here at base URL, which is console dot JumpCloud, cloud.com, we're going to grab all of our system users there. They're doing some filters. We're just going to go ahead and filter or remove all of the filters out of there for right now.

[00:09:42] Ben: Cool. Alright, so it looks like we got ourselves three users in our organization going back into our admin panel here. We've got 1, 2, 3 users, in fact. All right. And going through here, we see that we have our LDF admin. We've got it admin. These are all the users. This is fantastic. We even have John Babel.

[00:10:04] Ben: And if you look here, we have a department marketing, so let's go ahead and filter by the department marketing. So we're going to do a question mark filter, and I already have some stuff that are already pre-populated, but we're just going to do this manually. So we're going to say equals department, if I can type, right.

[00:10:20] Ben: And we're going to say, this is dollar sign equals, right? And we're going to say marketing just like that and hit send. And what we have now is we have a total. Right, which is John babble. He's part of the marketing department. We know that because we defined it as. Bam right there. This is a Jason object.

[00:10:40] Ben: So you can pretty much do this, you know, however, right. This is the pretty version. You can look at the raw version, which is just a dump of it. You can preview it even though it doesn't really do anything. So the pretty version of Jason, which is nice because it allows you to even collapse things, right?

[00:10:55] Ben: So if he wanted to collapse certain objects that are happening in here. You can, but this is all just one object. Cool. So that's getting a list of users now, what if you want to get a list of a specific user? So we can do that in a couple of ways. So once we can, we can come in here and we can do a filter and we can say username, right.

[00:11:15] Ben: And again, we can say equals and we can say a username was I think it was John dot babble.

[00:11:27] Ben: Well, there is no username dot, so it's two BS. It's two BS babble. Okay. There we go. We pulled that up. Now another way we can do it is by ID, right? So here is your ID, right? And that's another. Another end point. So you see here where it has ID. What we're gonna do is we're going to copy this ID here. We're gonna hit ID and we're going to list a specific system user.

[00:11:57] Ben: So if we go back into our documentation, look at system users, we want to list a system user, a very specific one user and. Again, we can do, we can do it by user ID, right? So this is where we want to get the user ID, that there are some filters. But again, I haven't really played with this cause like for instance, this is grabbing the user's directory, which is a V2 endpoint.

[00:12:26] Ben: Apparently there's some really cool other things that we can do that I need to dive into, but we were just going to go ahead and grab this particular user. So we're going to go ahead and dive back into postman. And again, we need to do what we need to grab our variables for these things. So we have our API.

[00:12:44] Ben: And we have our headers, which we have our X org ID as well. And then we're going to hit save on that. Alright. So now what we want to do is we have our ID, right. Which we want, we need to actually throw in there. So there a parameter here for filter, right? And then we have our. Okay. So we're not going to do any of that.

[00:13:07] Ben: We're just going to throw in the user ID directly into the parameter here. So we're going to go ahead and just do that. Okay. So then we're going hit. And that'll pull up the John babble object as well. Right? So we've got the exact same user by sending in the ape, the ID of that particular user really cool stuff.

[00:13:30] Ben: All right, let's go ahead and create a user. Now, if we want to look at creating a user, we want to post a system user. So there's only four fields that are required, but if you, if you do it, this is if you do this. We're going to create a system user. If you look at the body of this, right, it's got every field, every field.

[00:13:52] Ben: We don't want that business. So. We're just going to get rid of that and we're going to open up our Jason object and just for, cause I'm lazy, we're just going to grab this example here. We're just going to grab everything within the quotation marks here and we're going to throw that in there. Right.

[00:14:12] Ben: And there's a way that I can view. Sure. So now it's unified. Yay. Beautified. All right. So what we're going to do now is we're going to create a user called postman email address is postman at CS John klatt.com, which is a fake email address. And we're going to do last name or first name is going to be post and last name is going to be you guessed it, man.

[00:14:39] Ben: All right, let me show you two ends. Make it really cool, man. All right, cool. All right, so now we need, we need the the headers, right? So we need. API key, right? Which we are going to grab here. We're going to say API key. And then we also need our org ID, which we're going to throw in as well already.

[00:15:04] Ben: And we're going to hit save just for kicks and giggles. Right. You know, he needs to be saved because it's a little. Next to the, the endpoint. All right. So now we're gonna hit send, and if all went okay, we would get a status 200, the time that it took to do it, right. And then we should get a list of all the things that we, we sent to JumpCloud.

[00:15:25] Ben: So now, if I go back over into my JumpCloud admin panel, we now have our new user man post or post. Okay. And you go in here and it has all the information that we passed in really neat. Right. We can also delete a user, which we can, we can probably just do that real quick. Cause it wasn't that long of a process.

[00:15:50] Ben: Now that we've got it down so we can delete a system user. And what we need to do though, is we need to tie in the ID of that particular user. Well, we just created a user, right? So we got the idea. From that. So we know that ID. So when now we're going to go ahead and delete this user. So we're going to grab the ID of the user.

[00:16:08] Ben: And we're going to look at the header, right? So we've got our export X org ID and we've got our API key it save and send and bad request. Okay. So it looks like it's passing in a system, user ID. We don't really care about this park, bad requests and AOD. Oh,

[00:16:36] Ben: it's just a user ID. Okay. That's what we need. Alright. All right. So now we've got our status 200 and looks like we deleted that user. So if we go back into our admin portal here, you see that the, the post man user was completely deleted from our organization was really cool. Is that if you look at directory insights here, you actually can capture all of the things that we just did it.

[00:17:04] Ben: So I just deleted a user. Right. And you can see that the user that did it, you can see who I deleted the whole night. Right. All from directory insights. Then you can actually leverage those insights. It doesn't say that it was done through the API, which would have been, which would be very nice.

[00:17:27] Ben: Actually it does offer off method. API key right here. So your, your air AP your off method shows that it was the delete you, your user was done through the API key. So if you're looking for anything like in a SIM tool or alerting, and you want to see, Hey, what basically like end points or authorizations, are we getting it through the API key?

[00:17:51] Ben: You would basically just do the same thing. He would filter. The auth method being API key. And then you would get notifications through your SIM tool that this action, whether that be a deleting, a user or creating a user was done through the API key. So I hope that helps. I hope that gets everyone to start it.

[00:18:08] Ben: At least understanding how to use postman and how to get a very basic understanding of how to use. Cloud API and how to use post band to do testing. The next step would be to take this into some type of tool, like a, like I said, power out of mate, power automate or Zapier, or I FTT Integra mat, whatever the case might be.

[00:18:33] Ben: To then take these inferred pieces of information and map them to other pieces of data. Right? So if you had data coming in from another application or from your ticket manager, you'd be able to pass in these key value pairs, right. Account locked, true or false, right from those end points and be able to make direct changes to your jump cloud.

[00:18:58] Ben: Well, I hope that helps. If you do want to see more automations with the API please don't forget to like the video subscribe. Maybe even make a comment or two, let me know what you want to see. We can go ahead and start to create those. So again, thanks so much. Have a great day. See you next time.