Async OAuth Client for HTTPX

0.16.1 · active · verified Mon Apr 13

httpx-oauth is an asynchronous OAuth client library built on top of HTTPX. It provides clients for various OAuth2 providers (GitHub, Google, Facebook, etc.) as well as a generic OAuth2 client. The library is actively maintained with a regular release cadence, including minor versions introducing new features and breaking changes, and patch versions for bug fixes and dependency updates. Current version is 0.16.1.

Warnings

breaking Python 3.8 support was dropped in `v0.16.0`. Users on Python 3.8 or older must upgrade their Python version or stay on `httpx-oauth<0.16.0`.
Fix: Upgrade Python to 3.9+ or pin `httpx-oauth` to `<0.16.0`.
breaking All exception classes were moved from `httpx_oauth.oauth2` (and similar modules) to `httpx_oauth.exceptions`. Additionally, these exceptions now require a `message` property during instantiation.
Fix: Update import paths for exceptions (e.g., `from httpx_oauth.exceptions import GetAccessTokenError`) and ensure `message` is passed when raising them.
gotcha Older versions of `httpx-oauth` had strict upper bound constraints on `httpx` (e.g., `<0.28`). If you are upgrading `httpx` but not `httpx-oauth`, you might encounter dependency conflicts. `v0.16.1` removed the upper bound, allowing it to work with newer `httpx` versions.
Fix: Upgrade `httpx-oauth` to `0.16.1` or newer to remove the `httpx` upper bound constraint. If on an older version, ensure your `httpx` version adheres to the `httpx-oauth`'s specified range.
gotcha The `get_profile` method on OAuth2 clients (e.g., `GitHubOAuth2.get_profile`) was introduced in `v0.16.0`. Attempts to use this method on earlier versions will result in an `AttributeError`.
Fix: Upgrade `httpx-oauth` to `0.16.0` or newer to use the `get_profile` method. For older versions, you would need to implement the profile fetching logic manually using the `httpx` client.

Install

pip install httpx-oauth Install latest version

Imports

GitHubOAuth2

from httpx_oauth.clients.github import GitHubOAuth2

GoogleOAuth2

from httpx_oauth.clients.google import GoogleOAuth2

OAuth2
```
from httpx_oauth.oauth2 import OAuth2
```
GetAccessTokenError
```
from httpx_oauth.exceptions import GetAccessTokenError
```
As of v0.15.0, exception classes were moved to the `httpx_oauth.exceptions` module.

Quickstart

This quickstart demonstrates how to initialize a GitHub OAuth2 client and generate an authorization URL. It uses environment variables for client credentials, which is recommended for security. In a full application, you would capture the authorization code from the redirect URI and exchange it for an access token, then potentially fetch user profile information.

import asyncio
import os
from httpx_oauth.clients.github import GitHubOAuth2

async def main():
    CLIENT_ID = os.environ.get('GITHUB_CLIENT_ID', 'your_github_client_id')
    CLIENT_SECRET = os.environ.get('GITHUB_CLIENT_SECRET', 'your_github_client_secret')
    REDIRECT_URI = 'http://localhost:8000/callback'

    client = GitHubOAuth2(CLIENT_ID, CLIENT_SECRET)

    authorization_url = await client.get_authorization_url(
        redirect_uri=REDIRECT_URI,
        scope=['user:email']
    )
    print(f"Please visit this URL to authorize: {authorization_url}")

    # In a real application, you would handle the redirect from GitHub
    # and then exchange the code for an access token.
    # For demonstration, we'll simulate a code.
    # code = "<CODE_FROM_REDIRECT_URL>"
    # token_data = await client.get_access_token(code, REDIRECT_URI)
    # print("Access Token Data:", token_data)

    # Example of fetching user profile (requires access token)
    # if 'access_token' in token_data:
    #     user_profile = await client.get_profile(token_data['access_token'])
    #     print("User Profile:", user_profile)

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →