FastAPI Basic auth `realm` is REQUIRED but handled as

The Fix

pip install fastapi==0.128.4

Based on closed fastapi/fastapi issue #13471 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Open PR/Commit

@@ -0,0 +1,17 @@
@@ -0,0 +1,17 @@
+# Use Old 403 Authentication Error Status Codes { #use-old-403-authentication-error-status-codes }
+
+Before FastAPI version `0.122.0`, when the integrated security utilities returned an error to the client after a failed authentication, they used the HTTP status code `403 Forbidden`.

fix.md

Option A — Upgrade to fixed release\npip install fastapi==0.128.4\nWhen NOT to use: This fix should not be used if the application relies on the previous behavior of returning 403 status codes.\n\n

Why This Fix Works in Production

Trigger: and at related places, is misleading and makes it easy to create non-conforming APIs. It bit me when a Shelly device refused (rightfully) to authenticate…
Mechanism: The 'realm' parameter in Basic authentication was incorrectly handled as optional instead of required
Why the fix works: Changes the default status code for missing credentials from 403 to 401, aligning with RFC standards, and addresses the requirement for the 'realm' parameter in Basic authentication. (first fixed release: 0.128.4).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

The 'realm' parameter in Basic authentication was incorrectly handled as optional instead of required
Production symptom (often without a traceback): and at related places, is misleading and makes it easy to create non-conforming APIs. It bit me when a Shelly device refused (rightfully) to authenticate against the API which was using the default (missing) `realm` behavior.

Proof / Evidence

GitHub issue: #13471
Fix PR: https://github.com/fastapi/fastapi/pull/13786
First fixed release: 0.128.4
Reproduced locally: No (not executed)
Last verified: 2026-02-08
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.69

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Has The Issue Been Resolved Uptill Now ??”

@CODEKRUNCH · 2025-11-09 · confirmation · source

“Yeah this does look like a mistake to have "realm" as optional”

@Whizzo123 · 2025-03-11 · source

“looks to be getting fixed here https://github.com/fastapi/fastapi/pull/12507”

@Whizzo123 · 2025-03-11 · source

“Ah, good that this is already in the works! However, the fix to default it to "global" is questionable to me because that is a…”

@tvogel · 2025-03-11 · source

Failure Signature (Search String)

and at related places, is misleading and makes it easy to create non-conforming APIs. It bit me when a Shelly device refused (rightfully) to authenticate against the API which was
So, current version of RFC7235 doesn't say that `realm` is required.

Copy-friendly signature

signature.txt

Failure Signature
-----------------
and at related places, is misleading and makes it easy to create non-conforming APIs. It bit me when a Shelly device refused (rightfully) to authenticate against the API which was using the default (missing) `realm` behavior.
So, current version of RFC7235 doesn't say that `realm` is required.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
and at related places, is misleading and makes it easy to create non-conforming APIs. It bit me when a Shelly device refused (rightfully) to authenticate against the API which was using the default (missing) `realm` behavior.
So, current version of RFC7235 doesn't say that `realm` is required.

What Broke

APIs using default missing 'realm' behavior caused authentication failures with certain clients.

Why It Broke

The 'realm' parameter in Basic authentication was incorrectly handled as optional instead of required

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install fastapi==0.128.4

When NOT to use: This fix should not be used if the application relies on the previous behavior of returning 403 status codes.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/fastapi/fastapi/pull/13786

First fixed release: 0.128.4

Last verified: 2026-02-08. Validate in your environment.

When NOT to Use This Fix

This fix should not be used if the application relies on the previous behavior of returning 403 status codes.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Version Compatibility Table

Version	Status
0.128.4	Fixed

Related Issues

No related fixes found.

Cluster: fastapi:configuration-error FastAPI hub FastAPI best practices All hubs All clusters

Related clusters: Data consistency Rate limit Race condition

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

FastAPI Basic auth `realm` is REQUIRED but handled as optional (Fix)