Python httpx Authentication: Bearer Tokens and API Keys
Practical guide to authenticating httpx requests with bearer tokens and API keys, including reusable Auth subclasses, error handling, and security trade-offs.

To authenticate an httpx request with a bearer token, set the Authorization header to Bearer <token>. For an API key, set a header such as X-API-Key to the key, or pass it as a query parameter if the API requires it. Both schemes are common in REST APIs, but they differ in how the server expects the credential and how you should manage it in your Python code.
Sending a Bearer Token with httpx
The standard way to send a bearer token is through the Authorization header with the Bearer scheme. httpx does not have a dedicated bearer_token parameter, so you set the header explicitly:
import httpx
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
headers = {"Authorization": f"Bearer {token}"}
response = httpx.get("https://api.example.com/me", headers=headers)This works for both httpx.get() and httpx.Client() calls. When you use a Client, you can set the header once and reuse it across requests:
with httpx.Client(headers={"Authorization": f"Bearer {token}"}) as client:
response = client.get("https://api.example.com/me")
other = client.get("https://api.example.com/orgs")The Authorization header is the HTTP standard for bearer tokens, defined by RFC 6750. Most OAuth2-protected APIs expect this exact format: the literal word Bearer, a single space, then the token value. Do not add quotes around the token; the header value is the token itself. If you omit the Bearer prefix and send only the token, many servers reject the request with a 401 even though the token is valid.
Sending API Keys with httpx
API keys are less standardized than bearer tokens. Some APIs expect them in a custom header, others in a query parameter, and a few still use cookie-based delivery. You need to check the API documentation to know which one applies.
API Key in a Header
A common convention is X-API-Key, but many services use their own header name such as X-Auth-Token or X-Api-Key:
import httpx
api_key = "sk_live_4f8a2c..."
headers = {"X-API-Key": api_key}
response = httpx.get("https://api.example.com/data", headers=headers)API Key as a Query Parameter
Some APIs accept the key as a query parameter, typically named api_key or key:
import httpx
params = {"api_key": "sk_live_4f8a2c..."}
response = httpx.get("https://api.example.com/data", params=params)Query-parameter keys appear in server access logs, proxy logs, and browser history. If the API supports header-based keys, prefer that over the query parameter form. The header keeps the secret out of URLs, which is important because URLs are frequently logged and cached.
Using httpx.Auth for Reusable Authentication
If you make many authenticated calls across different parts of your codebase, setting headers manually on every request becomes repetitive and error-prone. httpx provides an Auth base class that lets you encapsulate the authentication logic and attach it to a Client.
import httpx
class BearerAuth(httpx.Auth):
def __init__(self, token: str):
self.token = token
def auth_flow(self, request: httpx.Request):
request.headers["Authorization"] = f"Bearer {self.token}"
yield requestYou then pass an instance to the client:
with httpx.Client(auth=BearerAuth(token)) as client:
response = client.get("https://api.example.com/me")The auth_flow method receives the outgoing request before it is sent. You modify the headers and yield the request back to httpx. This pattern is particularly useful when you need to refresh tokens: you can intercept a 401 response inside auth_flow, obtain a new token, modify the request, and yield it again.
import httpx
class RefreshingAuth(httpx.Auth):
def __init__(self, get_token):
self.get_token = get_token
def auth_flow(self, request: httpx.Request):
request.headers["Authorization"] = f"Bearer {self.get_token()}"
response = yield request
if response.status_code == 401:
# Call your token-refresh logic here so the next get_token() call returns a fresh token.
request.headers["Authorization"] = f"Bearer {self.get_token()}"
response = yield request
return responseNote that auth_flow is a generator. The first yield sends the request and receives the response back. If the response indicates an expired token, you can retry with a fresh one. This keeps token-refresh logic inside the authentication layer rather than scattered across call sites.
Handling Authentication Failures
An expired bearer token or an invalid API key typically produces a 401 Unauthorized response. Some APIs return 403 Forbidden when the key is valid but lacks permission for the resource. httpx does not raise an exception for these status codes by default; you must check response.status_code or use response.raise_for_status().
response = client.get("https://api.example.com/me")
if response.status_code == 401:
print("Token expired or invalid")
elif response.status_code == 403:
print("Authenticated but not authorized")
else:
response.raise_for_status()When you use raise_for_status(), a 401 or 403 raises httpx.HTTPStatusError. You can catch it and inspect the response for the exact status code. Do not assume that a 401 always means the token is expired; it can also mean the token was malformed, the header was missing, or the token was revoked.
Security Considerations for Tokens and Keys
Bearer tokens and API keys are credentials. Treat them with the same care as passwords.
Never hardcode tokens in source files. Use environment variables, a secrets manager, or a configuration file that is excluded from version control:
import os
import httpx
token = os.environ["API_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}Be aware that httpx logs request URLs by default when you enable logging. If you send an API key as a query parameter, that key will appear in the log output. Header-based credentials are not logged by default, but you should still avoid putting them in exception messages or print statements.
TLS is the transport layer that protects these credentials in transit. httpx verifies certificates by default, so a plain https:// URL is sufficient for most cases. Do not disable certificate verification in production; verify=False should only be used in controlled test environments where you understand the risk.
If you use a Client with a long lifetime, consider rotating tokens before they expire. The Auth subclass pattern makes this easier because the token source is centralized. For API keys that are long-lived, store them in a secrets manager and load them at startup rather than embedding them in code.
Choosing Between Bearer Tokens and API Keys
The choice is usually dictated by the API you are calling, not by httpx. Both are supported equally well by the library; the difference is in how the server expects the credential.
| Scheme | Typical header | Lifetime | Common use case |
|---|---|---|---|
| Bearer token | Authorization: Bearer <token> | Short-lived | OAuth2, user sessions |
| API key | X-API-Key: <key> | Long-lived | Service-to-service calls |
Bearer tokens are typically issued by an OAuth2 flow and expire after minutes or hours. They are often scoped to a specific user or permission set. API keys are usually static identifiers for a service account and remain valid until revoked.
When you control the server, prefer bearer tokens for user-facing endpoints because they support expiration and revocation. Use API keys for internal services where a long-lived credential is acceptable and rotation is handled operationally.
In httpx, the implementation cost is identical for both. The Auth subclass pattern works for either scheme, and the same client configuration applies. The operational difference — token refresh, key rotation, revocation — is what should drive your choice.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.