Install & Compatibility
Where this runs
tested against v0.23.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.312s · 22.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.282s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OAuth2AuthorizationCode
✓ from httpx_auth import OAuth2AuthorizationCode
AWS4Auth
✓ from httpx_auth import AWS4Auth
OktaAuthorizationCodePKCE
✓ from httpx_auth import OktaAuthorizationCodePKCE
MicrosoftEntraID
✓ from httpx_auth import MicrosoftEntraID
This quickstart demonstrates how to use `OAuth2AuthorizationCode` with HTTPX. It sets up an authentication object with placeholder OAuth2 URLs and a client ID. When `client.get()` is called, `httpx-auth` will manage the OAuth2 Authorization Code flow, typically by opening a browser for user interaction to obtain an access token, which is then used for the request. Remember to replace placeholder URLs and client ID with your actual values and configure the `redirect_uri` for your OAuth2 application if running locally.
import httpx
import os
from httpx_auth import OAuth2AuthorizationCode
# In a real application, these would come from environment variables or a secure configuration
# For this example, we use placeholders. Replace with your actual OAuth2 application details.
CLIENT_ID = os.environ.get("OAUTH_CLIENT_ID", "your_client_id")
AUTHORIZATION_URL = os.environ.get("OAUTH_AUTH_URL", "https://example.com/oauth/authorize")
TOKEN_URL = os.environ.get("OAUTH_TOKEN_URL", "https://example.com/oauth/token")
try:
auth = OAuth2AuthorizationCode(
client_id=CLIENT_ID,
authorization_url=AUTHORIZATION_URL,
token_url=TOKEN_URL,
# For local development, redirect_uri would typically be a local callback URL.
# httpx-auth will start a local server to capture the redirect.
# Ensure this matches what's configured for your OAuth2 client application.
# Example: redirect_uri="http://localhost:8000/callback", port=8000
)
with httpx.Client() as client:
# The first request will trigger the OAuth2 flow:
# 1. Opens a browser for user consent.
# 2. User grants permission, browser redirects to redirect_uri.
# 3. httpx-auth captures the code and exchanges it for a token.
# 4. The request to the protected resource is then made with the acquired token.
response = client.get("https://api.example.com/protected-resource", auth=auth)
response.raise_for_status()
print(f"Successfully authenticated and fetched data: {response.json()}")
except httpx.HTTPStatusError as e:
print(f"HTTP error occurred: {e.response.status_code} - {e.response.text}")
except httpx.RequestError as e:
print(f"An error occurred while making the request: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingWhen providing an `httpx.Client` instance as a parameter to any `httpx-auth` OAuth2 authentication class (e.g., `client` parameter in `OAuth2AuthorizationCode`), `httpx-auth` no longer closes this client automatically. Users are now responsible for explicitly closing these client instances when they are no longer needed to prevent resource leaks.fixEnsure you manage the lifecycle of `httpx.Client` instances passed to `httpx-auth` authentication classes. Wrap client usage in a `with httpx.Client() as client:` block or explicitly call `client.close()`.
affects: 0.23.0 and later
gotchaThe `AWS4Auth` class, ported from `requests-aws4auth`, has specific behavioral changes and deprecated attributes compared to its origin. Notably, the `amz_date` attribute has been removed, direct provision of `AWSSigningKey` instances is not supported (use explicit parameters instead), and the `date` parameter now defaults to `now()` without options to override or raise on invalid date.fixReview the `AWS4Auth` documentation for `httpx-auth` to understand the current parameter requirements and behaviors. Adjust your code to use explicit `access_id`, `secret_key`, and `region` parameters, and avoid relying on previously supported `requests-aws4auth` specific attributes or behaviors.
affects: All versions supporting AWS4Auth (0.22.0 and later)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'httpx'
The `httpx` library, which `httpx-auth` depends on, is not installed in your Python environment.
fixInstall `httpx` using pip: `pip install httpx`
TypeError: Invalid "auth" argument
The object provided to the `auth` argument of `httpx.Client` or `httpx.request` is not a valid authentication class or an instance of `httpx.Auth` or its subclasses, including those from `httpx-auth`.
fixEnsure you are passing an instantiated `httpx-auth` class (e.g., `OAuth2AuthorizationCode(...)`) or a valid `httpx.Auth` subclass instance to the `auth` parameter. Do not pass the class itself, or an object that does not conform to the expected authentication interface.
AttributeError: 'Request' object has no attribute 'body'
When implementing a custom authentication flow (or adapting one from `requests`), the `httpx.Request` object uses `request.content` for the request body, not `request.body` as used by `requests`.
fixReplace `request.body` with `request.content` in your custom authentication logic.
invalid_client
This OAuth2 error indicates that the client application's credentials (client ID, client secret) are incorrect, the client is not configured to use the requested grant type, or there's a mismatch in the authentication method used (e.g., `client_secret_basic` vs `client_secret_post`).
fixVerify that your `client_id` and `client_secret` are correct and securely managed. Ensure the OAuth2 application in your identity provider is configured to allow the grant type and authentication method you are using with `httpx-auth`. Check for typos, leading/trailing whitespace, or URL encoding issues.
Missing Authentication Token
When using AWS Signature Version 4 (SigV4) authentication with `httpx-auth` for AWS services, this error indicates that the request was not correctly signed, or the provided credentials (access key, secret key, region, service) are incorrect or lack necessary permissions.
fixDouble-check your AWS credentials (access key ID, secret access key), the specified AWS region, and the service name used in your `httpx_auth.AWSSigV4` configuration. Ensure your IAM entity has the required permissions for the API call.
Upgrade
Version history
0.23.1latest on PyPI · released Jan 7, 2025
Audit
Dependencies
httpxrequiredCore HTTP client library extended by httpx-auth.