 Assume your web API is protected and a client attempts to access it without the appropriate conditions. How do you deal with this scenario? Most likely, you know you have to return an HTTP status code. But what is the most appropriate one? Should it be 401 and authorized? Or should it be 403 forbidden? Or maybe even something else? As usual, it depends. It depends on the specific scenario and also on the security level you want to provide. In this video, we are going to see when to use 401 and authorized, and when to use 403 forbidden, and even discuss if something else is the best fit. Stay tuned. Before going into when to use each status code, let's take a quick look at the idea behind of the HTTP status codes in general. Most web APIs are inspired by the REST paradigm, and even though a vast majority of them don't actually implement REST, they usually follow a few RESTful conventions when it comes to HTTP status codes. The basic principle behind these conventions is that a status code returned in the response must make the client aware of what is going on and what the server expects the client to do next. You can fulfill this principle by giving answers to three questions. Is that a problem or not? If there is a problem, one which side is it? On the client side or the server side? And if there is a problem, what should the client do? In general, this principle applies to all status codes. For example, if the client receives a 200 OK, it knows that there is no problem with the request. On the other hand, if the client receives a 500 internal server error, it knows that the problem is on the server side, and that is anything that the client can do to fix it. In summary, your web API's response should provide the client with enough information to know how it can move forward. Let's start with a simple case. A client calls your protected API or meeting a required parameter. In this case, your API should respond with the 400 bad request status code. And since the parameter is required, your API can't even process the client's request because the request is malformed. Also, the client should be empowered to understand how to fix the problem. So you should add in your response body what's wrong with the client's request. And you can provide those details in the format you prefer, such as simple tags, HTML or JSON, and so on. For example, if your client calls your API with an empty value for the required data parameter, the API could reply with the JSON stating that that data parameter can't not be blank. In a new case, let's assume that your client calls your protected API with a well-formed request but no valid credentials. In the context of OAuth 2, this means the request either is missing an access token or the present access token is expired, revoked, malformed, or invalid for any other reasons. In any of these two situations, the appropriate status code for the response is 401 unauthorized. In the spirit of mutual collaboration between the client and the API, the response then must include a hint on how to obtain such authorization. And that hint comes in the form of a www.authenticate header with the specific authentication scheme to use. For example, the response could indicate that the client needs a better scheme and provide the round parameter to indicate the set of resources the API is protecting. And even include the reason for the denied access. On the other hand, if the client request does not include any access token, it's safe to assume that the client wasn't aware that the API is protected. And because of that, the API's response should not include any other information. Now, let's explore a different case. Let's say that the client sends a request to modify a document and provides a valid access token to the API. However, that token does include any permissions or scopes that allow the client to perform that desired action. In this case, your API should respond with 403, and three, repeatedly. With this status code, your API tells the client that the credentials provided the access token are valid, but it lacks the appropriate privileges to perform the requested action. To help the client understand what to do next, the API may include what privileges are needed in this response. And according to our two guidelines, the API may include information about the missing scope to access the protected resource. Now that you know when to use each status code, let's talk about security. Because when you plan how to respond to your client's request, you will always have to keep security in mind. Since this additional information is optional for both the HTTP specifications and the all-of-two-bearer token guidelines, you should think carefully about sharing it. Even though sharing this information can improve the collaboration between the API and the client, the same information may be used by malicious attackers to elaborate the attack strategy. For example, suppose your API returns a 401 and authorized with a narrow description that the access token is expired. In this case, the API is giving out information about the token itself to a potential attacker. The base principle on sharing that additional information should be based on the answer to this question. Would the client behave any differently if provided with more information? For example, in the case of a response with a 401, does the client with behavior change when he knows that the token is expired or revoked? Either way, the client must request the new token. So adding that information doesn't really change the client's behavior. But if the situation were different with the 401 forbidden, by informing your client that he needs a specific permission, your API makes the client learn what to do next. For example, requesting additional permission. If your API doesn't provide this additional information, the client will behave differently because he doesn't know what to do to access their resource. Now, let's assume your client attempts to access a resource that he must not access at all. For example, because it belongs to another user. Because the resource shouldn't be reached by the current client, the best option is to hide it. Letting the client and specifically the user behind it know the resource exists could possibly lead to an insecure direct object references or ID or R. An access control vulnerability based on the knowledge of resources you shouldn't access. In these cases, your API should respond with a follow for not found status code. This is an option provided by the HTTP specification. And I quote, a not engine server that wishes to hide the current existence of a forbidden target resource may instead respond with the status code of 404 not found, unquote. For example, this is the strategy adopted by GitHub when you don't have any permission to access a report story. This approach avoids that an attacker attempts to access the resource again with a slightly different strategy. When a client sends a mouth form request, now you know you should reply with 400 by request. You may be tempted to analyze the request and its correctness before evaluating the client credentials. You shouldn't do this for a few reasons. First, by evaluating the client credentials before the request validity, you avoid that your API processing the request that aren't allowed to be there anyways. And second, a potential attacker could figure out how a request should look without being authenticated even before obtaining or stealing a legitimate access token. Also, consider that the infrastructure is within an API gateway, for example. The client credentials will be evaluated beforehand by the gateway itself, which doesn't know what parameters the API is expecting. And one final piece of advice is that the security measures discussed here must be applying in the production environment. And in the development environment, your API can provide all the information you need to be able to diagnose the causes for an authorization failure. You've reached the end of this video. And I know this is a lot of information. So to help you remember when to use each status code, we have a great cheat sheet linked below. You can use it whenever you want and even share it with friends. All of the topics discussed here today are also available in the blog post linked below and I encourage you to check that out. I'll see you soon.