Authorizing Requests in Postman

Welcome to the short video series for people who are new to Postman. If you've missed the previous video, make sure to check the video description. In this video, we'll take a closer look at how you can authorize a request in Postman. Not all APIs can be accessed without providing some kind of credentials. In other words, the API must know who we are, and check if you are allowed to access or change the data. For this example we will use the GitHub API. If you don't have a GitHub account yet, please create one for this tutorial. I'm going to open up the GitHub API documentation and you will find the link in the video description. Now let's try to go through the documentation and figure out what we need to do to create a new repository by using the GitHub API. So if I want to create a repository I will go through the reference. and search for something in relation to repositories. So let's take a look here to see if there's a way to create a repository. We'll find here create a repository for the authenticated user. So what we have here is information about creating a new repository for the authenticated user and we have here the endpoint slash user slash repos and this needs to be a post request. The base URL that we're using for this request is api.github.com. So we're going to start with this, go inside Postman, open up a new tab, paste this. Since we want to create a post request to create a repository, I'm going to select here post from the drop down and I will also add the endpoint which is slash user slash repos. So let's go ahead and try to submit this. Now, while we haven't provided anybody in terms of exactly how we'd like to name this repository, we can notice that this is currently not working. We're getting back 401 unauthorized. So 401 unauthorized simply means that we are not authorized to create a repository because we haven't provided any credentials. Essentially, it doesn't make sense to create a repository if GitHub doesn't know who we are. So we need to find a way to authenticate ourselves. Now, most of the time when working with APIs, we're not providing our username and password. We use tokens, which are a form of a temporary password that gives us sometimes limited access to our account. Let's go ahead to github.com and create a token. This is my GitHub account. And from my profile, I will go to settings. And from the settings menu, I'll go to developer settings and select personal access tokens. So I'm going to click here on generate new token. And now we have to provide some details to this token. So for example, the note is very important because later on you should know why you have created this token. So I'm going to write here postman and I'm going to also select a very low expiration date. So essentially, after seven days, this token will expire and I will not be able to use it anymore. Additionally, we'll also select some scopes and scopes are a way to tie some permissions to this token that we're creating. By default, with our username and password, we have full access over our GitLab account. But in this case, we only want to create a repository. So it doesn't make sense to give Postman, in this case, permissions to do other things that we didn't intend to do. So for that reason, let's only give the permissions that are needed. So I'm going to select here only repo and by scrolling down, I'll go to generate token. Now for any hackers out there, I have invalidated this token right after finishing the recording. So make sure that you use your own token and not what you see right now on the screen. I'm going to simply click here on copy, go back to Postman. And what Postman does is to offer us some authentication helpers. These are essentially some built-in tools that makes our life a bit easier. So from the authorization tab below the URL of the request, I'll select here authorization. And from the drop-down list, I will select the bearer token. And I can paste the token here. And now we can click on Send. Now you will see we are no longer getting a 401 status code, we're getting 400 bad requests. And it's telling us that the body should be a JSON object. So obviously, now the authentication is working. And we just have to figure out how to submit a valid body that is API will understand. Now since we're making progress, let's go ahead and save this request. For this case, I'm going to create a new collection. I'm going to call it GitHub API. And the name of the request will be create repository. Going back to the authorization, you will see here that Postman is trying to warn us. It's not a good idea to... put here sensitive data inside the request as later on we may want to share this collection with someone else and we don't want to expose our private tokens so for that reason i want to introduce you to the concept of variables so what i'm going to do next is i'm going to select here this value and you will see here that this option set as a variable will appear i'll click here set as a new variable i'll call it token and I'm going to select the scope collection. Now if you haven't saved this request in a collection yet, you have to do it first before you can see here the possibility of saving this in a collection. I'm going to click here on set variable. Now if you hover over this value, you will see here the value that has been saved. And this is the syntax that Postman uses inside request. When working with variables, you will see this curly brackets, two curly brackets in the beginning and two at the end, and the name of the variable in the middle. This will be replaced by postman. So if I click here on send, you will see I'm not getting a 401. This is still working properly. If we need to make changes to this variable, all we have to do is to go to the request, open the context menu and select Edit. You will see here a tab inside a collection called variables. Now what we have done we have saved this value with this token to a variable which is called token and now we have these two values initial value and current value this is where a lot of beginners get confused and i just want to point out the difference between the initial value and the current value the initial value is something that will be shared with others so if you go ahead and share this collection with someone else they will be able to see the initial value so for that reason it makes sense to have here in the initial value something like put your token or something that will indicate to the person receiving your collection that they need to put their their own token and they shouldn't use your value the current value is private to your account and it's what postman uses so it's totally safe to have an initial value like something that would be obviously invalid and the current value which is your actual value that you want to use the valid token that you want to use for this request so i'm going to click here on save And if you go back to our request itself, this is still working properly. What this authorization helper did is to create a new header. So if you click here on the headers, you will see here that a new header authorization has been added. It has the value bearer space, and this is the token that we have provided. Now, headers are another way how you can pass data to the API. Generally, headers are not directly connected to the endpoint itself. So for example, you would rarely use a header to filter some information, you would use query parameters for that. But kind of like headers provide authentication information or other kind of information that is useful to ensure that this message will be properly delivered and understood by the API. So it is a bit more technical, but at least for authorization purposes, this is where you'll see most of the time. tokens being passed. Now since our request is still failing, let's figure out what we need to send in order to create this repository. So we're going to go back to the API documentation, and we already know that we need to send some information, and that information needs to be formatted as JSON. And if you're looking here, we have some parameters. From what I see, the only parameter that is required is name. This is the name of the repository. There's also other parameters that we can submit, description and so on. And you will see here that these are all body. So the API expects these parameters to be part of the body. So let's go ahead and create a valid JSON with a name and a description. So we already selected a post request. I'm going to go to body, select raw, and from the list that appears here, we'll select JSON. So let's start giving it a name. Let's say created from Postman. And we can also give it a description. All right. So let's click on the send button again. And this time we'll see here 201 created. It means that we now have created a new resource, we have created a new repository, and in the response you will get some details about this repository, like some internal ID, the name of the repository, where you can find it in your profile, and so on. We can also go to our GitHub profile, open up the repositories, and you will see here, right on top, created from Postman. Now this is an empty repository, but instead of using the GitHub web interface, we have used the GitHub API to create this repository. Now at this point you might be getting some errors, and I just wanted to point out some of the most typical mistakes that beginners make. When you're getting an error, it's important to look at the status code to understand the type of error you are getting, and also to look for hints in the response. For example, here previously. If we don't provide a body, we'll get back a 400 bad request, which means that there's something wrong with our request. And we'll get hints here saying the body should be a JSON object. It's also possible that you provide a body, but you make some mistakes. So you transform it in something that's invalid, and Postman will try to help you out. But if you still ignore it, we'll get another error saying problems parsing JSON, and you will need to fix this on your own. If you're getting a 404 status code, make sure that your address is correct. For example, here simply adding a space after my address, I'm getting a 404 not found. Because this extra space means another address, but this other address doesn't exist. If you're getting 401, make sure that you have configured the bureau token correctly. Also, anything weird inside the bureau token like a space or any unwanted characters will make this value invalid. Also, check the video description for some troubleshooting ideas, post a comment in the section below, or even better, post a question in the postman community if you're facing any issues.

Not all APIs can be accessed without providing some kind of credentials. In other words, the API must know who we are, and check if you are allowed to access or change the data. For this example we will use the GitHub API. If you don't have a GitHub account yet, please create one for this tutorial. I'm going to open up the GitHub API documentation and you will find the link in the video description.

Now let's try to go through the documentation and figure out what we need to do to create a new repository by using the GitHub API. So if I want to create a repository I will go through the reference. and search for something in relation to repositories.

So let's take a look here to see if there's a way to create a repository. We'll find here create a repository for the authenticated user. So what we have here is information about creating a new repository for the authenticated user and we have here the endpoint slash user slash repos and this needs to be a post request.

The base URL that we're using for this request is api.github.com. So we're going to start with this, go inside Postman, open up a new tab, paste this. Since we want to create a post request to create a repository, I'm going to select here post from the drop down and I will also add the endpoint which is slash user slash repos. So let's go ahead and try to submit this.

Now, while we haven't provided anybody in terms of exactly how we'd like to name this repository, we can notice that this is currently not working. We're getting back 401 unauthorized. So 401 unauthorized simply means that we are not authorized to create a repository because we haven't provided any credentials.

Essentially, it doesn't make sense to create a repository if GitHub doesn't know who we are. So we need to find a way to authenticate ourselves. Now, most of the time when working with APIs, we're not providing our username and password.

We use tokens, which are a form of a temporary password that gives us sometimes limited access to our account. Let's go ahead to github.com and create a token. This is my GitHub account.

And from my profile, I will go to settings. And from the settings menu, I'll go to developer settings and select personal access tokens. So I'm going to click here on generate new token.

And now we have to provide some details to this token. So for example, the note is very important because later on you should know why you have created this token. So I'm going to write here postman and I'm going to also select a very low expiration date. So essentially, after seven days, this token will expire and I will not be able to use it anymore.

Additionally, we'll also select some scopes and scopes are a way to tie some permissions to this token that we're creating. By default, with our username and password, we have full access over our GitLab account. But in this case, we only want to create a repository. So it doesn't make sense to give Postman, in this case, permissions to do other things that we didn't intend to do. So for that reason, let's only give the permissions that are needed.

So I'm going to select here only repo and by scrolling down, I'll go to generate token. Now for any hackers out there, I have invalidated this token right after finishing the recording. So make sure that you use your own token and not what you see right now on the screen. I'm going to simply click here on copy, go back to Postman. And what Postman does is to offer us some authentication helpers.

These are essentially some built-in tools that makes our life a bit easier. So from the authorization tab below the URL of the request, I'll select here authorization. And from the drop-down list, I will select the bearer token. And I can paste the token here.

And now we can click on Send. Now you will see we are no longer getting a 401 status code, we're getting 400 bad requests. And it's telling us that the body should be a JSON object.

So obviously, now the authentication is working. And we just have to figure out how to submit a valid body that is API will understand. Now since we're making progress, let's go ahead and save this request.

For this case, I'm going to create a new collection. I'm going to call it GitHub API. And the name of the request will be create repository.

Going back to the authorization, you will see here that Postman is trying to warn us. It's not a good idea to... put here sensitive data inside the request as later on we may want to share this collection with someone else and we don't want to expose our private tokens so for that reason i want to introduce you to the concept of variables so what i'm going to do next is i'm going to select here this value and you will see here that this option set as a variable will appear i'll click here set as a new variable i'll call it token and I'm going to select the scope collection.

Now if you haven't saved this request in a collection yet, you have to do it first before you can see here the possibility of saving this in a collection. I'm going to click here on set variable. Now if you hover over this value, you will see here the value that has been saved. And this is the syntax that Postman uses inside request. When working with variables, you will see this curly brackets, two curly brackets in the beginning and two at the end, and the name of the variable in the middle.

This will be replaced by postman. So if I click here on send, you will see I'm not getting a 401. This is still working properly. If we need to make changes to this variable, all we have to do is to go to the request, open the context menu and select Edit.

You will see here a tab inside a collection called variables. Now what we have done we have saved this value with this token to a variable which is called token and now we have these two values initial value and current value this is where a lot of beginners get confused and i just want to point out the difference between the initial value and the current value the initial value is something that will be shared with others so if you go ahead and share this collection with someone else they will be able to see the initial value so for that reason it makes sense to have here in the initial value something like put your token or something that will indicate to the person receiving your collection that they need to put their their own token and they shouldn't use your value the current value is private to your account and it's what postman uses so it's totally safe to have an initial value like something that would be obviously invalid and the current value which is your actual value that you want to use the valid token that you want to use for this request so i'm going to click here on save And if you go back to our request itself, this is still working properly. What this authorization helper did is to create a new header. So if you click here on the headers, you will see here that a new header authorization has been added.

It has the value bearer space, and this is the token that we have provided. Now, headers are another way how you can pass data to the API. Generally, headers are not directly connected to the endpoint itself.

So for example, you would rarely use a header to filter some information, you would use query parameters for that. But kind of like headers provide authentication information or other kind of information that is useful to ensure that this message will be properly delivered and understood by the API. So it is a bit more technical, but at least for authorization purposes, this is where you'll see most of the time.

tokens being passed. Now since our request is still failing, let's figure out what we need to send in order to create this repository. So we're going to go back to the API documentation, and we already know that we need to send some information, and that information needs to be formatted as JSON.

And if you're looking here, we have some parameters. From what I see, the only parameter that is required is name. This is the name of the repository. There's also other parameters that we can submit, description and so on. And you will see here that these are all body.

So the API expects these parameters to be part of the body. So let's go ahead and create a valid JSON with a name and a description. So we already selected a post request.

I'm going to go to body, select raw, and from the list that appears here, we'll select JSON. So let's start giving it a name. Let's say created from Postman. And we can also give it a description.

All right. So let's click on the send button again. And this time we'll see here 201 created. It means that we now have created a new resource, we have created a new repository, and in the response you will get some details about this repository, like some internal ID, the name of the repository, where you can find it in your profile, and so on. We can also go to our GitHub profile, open up the repositories, and you will see here, right on top, created from Postman.

Now this is an empty repository, but instead of using the GitHub web interface, we have used the GitHub API to create this repository. Now at this point you might be getting some errors, and I just wanted to point out some of the most typical mistakes that beginners make. When you're getting an error, it's important to look at the status code to understand the type of error you are getting, and also to look for hints in the response.

For example, here previously. If we don't provide a body, we'll get back a 400 bad request, which means that there's something wrong with our request. And we'll get hints here saying the body should be a JSON object.

It's also possible that you provide a body, but you make some mistakes. So you transform it in something that's invalid, and Postman will try to help you out. But if you still ignore it, we'll get another error saying problems parsing JSON, and you will need to fix this on your own.

If you're getting a 404 status code, make sure that your address is correct. For example, here simply adding a space after my address, I'm getting a 404 not found. Because this extra space means another address, but this other address doesn't exist. If you're getting 401, make sure that you have configured the bureau token correctly.

Also, anything weird inside the bureau token like a space or any unwanted characters will make this value invalid. Also, check the video description for some troubleshooting ideas, post a comment in the section below, or even better, post a question in the postman community if you're facing any issues.

Transcript for:Authorizing Requests in Postman

Transcript for:
Authorizing Requests in Postman