Authentication with Python Requests: A Complete Guide

In this tutorial, you’ll learn how to provide authentication for the requests you make with the Python requests library. Many web services, such as APIs, require authentication. This can often be a daunting topic for beginner or novice programmers, alike. This is especially true, given that there are many different types of authentication. Thankfully, the requests library comes with a large number of different authentication methods built-in, making the process simple and easy.

By the end of this tutorial, you’ll have learned:

• How to use basic authentication with Python requests
• How to use a basic authorization token as credentials with Python requests
• How to use digest authentication with Python requests
• How to use OAuth1 authentication with Python requests
• How to use OAuth2 and OpenID Connect with Python requests
• How to create your own authentication methods for using with Python requests

Use Basic Authentication with Python Requests

Basic authentication refers to using a username and password for authentication a request. Generally, this is done by using the HTTPBasicAuth class provided by the requests library. However, as you’ll later learn, the requests library makes this much easier, as well, by using the auth= parameter.

Let’s see how we can pass in a username and password into a simple GET request using the HTTPBasicAuth class:

# Authentication in Requests with HTTPBasicAuth
import requests
from requests.auth import HTTPBasicAuth
auth = HTTPBasicAuth('user', 'pass')

print(requests.get('https://httpbin.org/basic-auth/user/pass', auth=auth))

# Returns: <Response [200]>

Let’s break down what we did in the code above:

1. We imported both the requests library as well as only the HTTPBasicAuth class
2. We then created a new HTTPBasicAuth object, auth, which contains a string for the username and password
3. Finally, we printed the Response we returned when passing our auth variable into the auth= parameter of the get() function

If you were using this method, you’d change 'user' and 'pass' to the username and password of your choice.

Because the basic authentication method is used so frequently, the requests library abstracts away some of this complexity. Rather than needing to create a new HTTPBasicAuth object each time, you can simply pass a tuple containing your username and password into the auth= parameter.

Let’s see what this looks like:

# Simplifying Basic Authentication with Python requests
import requests

print(requests.get('https://httpbin.org/basic-auth/user/pass', auth=('user', 'pass')))

# Returns: <Response [200]>

In the code above, we were able to significantly reduce the complexity of our code. The Python requests library handles a lot of the boilerplate code for us!

In the following section, you’ll learn how to use digest authentication in the Python requests library.

Use a Basic Authorization Token as Credentials with Python Requests

Many APIs will simply provide you with a basic authorization (or, auth) token instead of credentials. The Python requests library makes working with these types of authorizations very easy. These tokens can easily be embedded in the headers of a request that’s being made.

In order to use basic authorization tokens as credentials, simply pass the token into the Authorization header of a request:

# Using an Authorization Token as Credentials
import requests

headers = {'Authorization': 'abcde12345'}
print(requests.get('https://httpbin.org/basic-auth/user/pass', headers=headers))

# Returns: <Response [200]>

The requests library accepts headers in the form of a Python dictionary. In the example above, we passed in a sample token as a string. Simply switch out the token you’re using with your own API key and pass it into the headers parameter.

Use Digest Authentication with Python Requests

A very common way of authenticating HTTP requests is to use the digest authentication method. Similar to the Basic HTTP Authentication method shown above, the requests library provides a class to help with digest authentication.

Let’s see how you can use the HTTPDigestAuth class to authenticate using digest authentication in Python:

# Authentication in Requests with HTTPDigestAuth
import requests
from requests.auth import HTTPDigestAuth
auth = HTTPDigestAuth('user', 'pass')

print(requests.get('https://httpbin.org/basic-auth/user/pass', auth=auth))

# Returns: <Response [200]>

Let’s break down what we did in the code block above:

1. We imported requests and the HTTPDigestAuth class from the auth module
2. We then created an auth object by passing our username and password into the class constructor
3. Then, we made a request and printed out the response

In the following section, you’ll learn how to use OAuth1 authentication with the Python requests library.

Use OAuth1 Authentication with Python Requests

A very common form of authentication when using web APIs is the OAuth form of authentication. Generally, OAuth authentications come with a client key, client secret, a resource key, and a resource secret. While this may seem like a lot, it’s simple to provide to your request.

In order to use OAuth1 authentication, you need to install the requests-oauthlib library. This can be done easily using the pip installer:

# Installing the requests-oauthlib library
$ pip install requests requests-oauthlib

Once the library is installed, you can authentication using OAuth1 using the following code:

# Authenticating Using the OAuth1 Authentication Method
import requests
from requests_oauthlib import OAuth1

url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
auth = OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET',
              'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')

requests.get(url, auth=auth)
<Response [200]>

The OAuth1 method was replaced by the OAuth2 authentication protocol in 2012, making it much more robust and reliable. In the following section, you’ll learn how to authenticate using the OAuth2 method.

Use OAuth2 and OpenID Connect Authentication with Python Requests

The OAuth2 authentication protocol is a more robust and reliable protocol than the OAuth1 method. Similar to the method shown above, the OAuth2 authentication uses access tokens. These access tokens are special kinds of data, often in the form of JSON, that allow users to authenticate for a site or a particular resource. Additionally, these tokens often have an expiry date and time in order to keep them more secure.

In order to use OAuth2 with the requests library, you need to install the requests-oauthlib library. This can be done easily using the pip installer:

# Installing the requests-oauthlib library
$ pip install requests requests-oauthlib

Once the library is installed, you can authentication using OAuth2 using the following process:

1. Obtain credentials from the provider manually. Generally, this will include a client_id, but likely also a client_secret. In some cases, you’ll also need to register a default redirect URI to be used by your application.
2. Create a OAuth2 session using the requests-oauthlib library
3. Fetch the token from the session object
4. Access the resources using the session object

# Authenticating with OAuth2 in Requests
from requests_oauthlib import OAuth2Session

# Inlcude your data
client_id = "include your client_id here"
client_secret = "include your client_secret here"
redirect_uri = "include your redirect URI here"

# Create a session object
oauth = OAuth2Session(client_id, redirect_uri = redirect_uri)

# Fetch a token
token = oauth.fetch_token("<url to fetch access token>", client_secret = client_secret)

# Get your authenticated response
resp = oauth.get("URL to the resource")

This process was a bit more complicated. However, this is a worthwhile method to learn given the prevalence of OAuth2. In the following section, you’ll learn how to authenticate using custom methods in the Python requests library.

Create Custom Authentication Methods for Python Requests

In some cases, the required form of authentication won’t exist in the requests library. Thankfully, the library allows you to create your own forms of authentication by providing a general structure via a subclass.

Let’s see how we can create our own form of authentication by inheriting from the AuthBase class:

# Creating a Custom Authentication Method
import requests
from requests.auth import AuthBase

class CustomAuth(AuthBase):
    def __call__(self, r):
        # Implement authentication here
        return r

requests.get(url, auth=CustomAuth())

In the code above, we demonstrated the basic requirements for how to construct your own form of authentication:

1. We imported the requests library and the AuthBase class
2. We then created our own class, inheriting from the AuthBase class
3. The class only have the __call__() method implemented, currently
4. The class can then be used the auth= parameter of a HTTP request

Conclusion

In this tutorial, you learned how to provide authentication for the requests you make with the Python requests library. Because most web APIs and services require some form of authentication, having a good handle on how to perform these with the requests library is an important skill. You first learned how to use basic authentication, digest authentication, and token authentication. Then, you learned how to use OAuth1 and OAuth2, as well as custom authentication implementations.

Additional Resources

To learn more about related topics, check out the tutorials below:

• response.json() – Working with JSON in Python requests
• Python requests: POST Request Explained
• Python requests Authentication Official Documentation