🐛 Use `401` status code in security classes when credentials are missing #13786

YuriiMotov · 2025-06-11T17:44:55Z

Warning

This description is partially outdated after changes described in this comment.

Description

This PR is an attempt to finally solve the issue with security tools returning error responses with status code 403 instead of 401 when credentials are not provided.

Breaking changes and workaround

These changes can break projects that rely on old behavior.
In order to mitigate this, the not_authenticated_status_code is introduced. If set to 403, it will make it work the same way as it was before changes (return 403 status code).
This option should be treated as a temporary workaround to give developers more time to update Clients to follow the new behavior.

Changes and reasoning

APIKeyQuery, APIKeyHeader, APIKeyCookie

Standard:
- These schemes are not covered by standards, but developers usually follow the same rules as for other standards
Actions:
- The default status code for not providing API key was changed from 403 to 401.
- Temporary not_authenticated_status_code parameter can be used to revert this behavior back to returning 403 error code without sending WWW-Authenticate.
Notes:
- It’s considered to be a good practice to include in WWW-Authenticate information needed to understand how the key is supposed to be passed. I implemented default format (WWW-Authenticate: ApiKey in="...", name="..." ), but it’s possible to override the template for WWW-Authenticate by subclassing and defining the format_www_authenticate_header_value method

HTTP Basic

Standard:
- https://datatracker.ietf.org/doc/html/rfc7617
Actions:
- No needed. This scheme already acts according to the standard in terms of returning 401 status code with WWW-Authenticate header on a lack of credentials
Notes:
- realm is required according to the RFC, but optional in the current implementation. Fixing this would introduce breaking changes. Considering this is not a problem for people who want to follow the standard, I suggest we leave it as it is.

HTTP Digest

Standard:
- https://datatracker.ietf.org/doc/html/rfc7616
Actions:
- The default status code for not providing the authorization parameter was changed from 403 to 401.
- WWW-Authenticate is just a stub for now (just WWW-Authenticate: Digest) (see notes)
- Temporary not_authenticated_status_code parameter can be used to revert this behavior back to returning 403 error code without sending WWW-Authenticate.
Notes:
- Since the current HTTPDigest implementation is just a stub, we can’t follow standards (we don’t generate nonce's, don’t have realm, …). I suggest we just change the error status code and add a stub for WWW-Authenticate (just WWW-Authenticate: Digest). For now HTTPDigest can’t be used as it is, so, this is not a problem.
- We can later add full implementation of Digest scheme. There have been made several attempts to implement it (Update HTTPDigest to match RFC 7616 #9825, 🔒 Match HTTP Digest specs from RFC 7616 #3071)
- Should we add a note that HTTPDigest is just a stub?

HTTP Bearer, OAuth2 schemes, OIDC

Standard:
- https://datatracker.ietf.org/doc/html/rfc6750
Actions:
- For OAuth2PasswordBearer and OAuth2AuthorizationCodeBearer: not needed.
  - They already return a 401 error code. Implementation is probably not 100% correct (see notes), but considering nobody argued, I think we can leave it as it is for now.
- For HTTPBearer and OpenIdConnect:
  - The default status code for not providing the authorization parameter was changed from 403 to 401. The suggested implementation will be in line with the current implementations of OAuth2PasswordBearer and OAuth2AuthorizationCodeBearer.
  - Temporary not_authenticated_status_code parameter added to HTTPBearer can be used to revert this behavior back to returning 403 error code without sending WWW-Authenticate.
Notes:
- It’s recommended to return 400 error response if the parameter is missed or of an unsupported type, but this is not a strict requirement (word SHOULD is used). I suggest we ignore this and follow the approach that is consistent with other schemes.
- The format of WWW-Authenticate is not clearly described: It’s said that the value "Bearer" MUST be followed by one or more auth-param values. At the same time, all auth-param attributes are optional. In examples they always add realm. Since we don’t have realm, I suggest we just skip it and send just WWW-Authenticate: Bearer
- We can later improve the WWW-Authenticate format by adding realm and scope

Links

…rror

…" error

bjmc · 2025-07-15T12:35:35Z

Thank you for opening this @YuriiMotov - we've just been surprised by an API reporting 403 for a missing token when we we'd be expecting to see 401 and trigger a login flow on the client side.

We'd be glad to have this this fix merged. 🙏

(fwiw, I agree with the decision to follow other implementations and return 401 not 400)

stg609 · 2025-08-06T11:41:12Z

Any progress?

Cito · 2025-08-06T11:52:40Z

We have been also noticing this and are waiting for a fix for a long time.

cleder · 2025-08-28T19:33:07Z

I ran into this too when using schemathesis testing a route protected by HTTPBearer

  | schemathesis.core.failures.FailureGroup: Schemathesis found 2 distinct failures
  | 
  | - Missing header not rejected
  | 
  |     Missing header not rejected (got 403, expected 401)

cleder

The if self.not_authenticated_status_code == HTTP_403_FORBIDDEN: checks look a bit clunky, but given this is of a temporary nature it is probably fine

…o create the exception to be raised

… refactored into subclassing

…ame type of error for invalid authentication

…urity utils

tiangolo

Awesome, thank you @YuriiMotov! 🙌

And thank you for all the investigation and notes with all the research. 🤓 ☕

I made the following updates:

Simplify the WWW-Authenticate challenge for API key, as this is a custom challenge we are defining, I didn't want to also define custom parameters, but leave the simplest form.
Refactor the implementation to not have an extra parameter for defining the status code, instead, put the creation of the error in a method of the class, this way if someone wants to use the old behavior, they can create a subclass and override only that method.
Refactor the HTTP classes to all return the same message for errors ("Not authenticated"), instead of some times returning "Invalid authentication credentials", this simplifies the code a bit, and in particular makes it simpler to explain to users how to use the old behavior.
Simplify and refactor a bit the implementation.
Add new docs for how to use the old behavior by subclassing, with new source examples and tests for them.
Add notes and warnings about stub classes, as you suggested.

I also noted that the spec says that the realm is now optional, but only in a footer note (https://datatracker.ietf.org/doc/html/rfc7235#appendix-A). 😂 Anyway, we are good with that now.

This will be available in FastAPI 0.122.0, released in the next few hours. 🎉

github-actions · 2025-11-24T18:38:02Z

📝 Docs preview

Last commit 61d703e at: https://f4ebcc3e.fastapitiangolo.pages.dev

Modified Pages

https://f4ebcc3e.fastapitiangolo.pages.dev/how-to/authentication-error-status-code/ - (before)

* Sync with #14217 * Sync with #14359 * Sync with #13786 * Sync with #14070 * Sync with #14120 * Sync with #14211 * Sync with #14405 * "to deploy" -> "deployen" The LLM used that translation a lot ithis convinced me that "deployen" it is the better word. "bereitstellen" (or "ausliefern") is still used for "to serve". --------- Co-authored-by: Motov Yurii <[email protected]> Co-authored-by: Yurii Motov <[email protected]>

YuriiMotov added 10 commits June 9, 2025 12:29

Move common logic of APIKey** classes to APIKeyBase class

19daeca

Fix APIKey** security schemes status code on "Not authenticated" error

c653eef

Fix HTTPBearer security scheme status code on "Not authenticated" e…

6c53a67

…rror

Fix HTTPDigest security scheme status code on "Not authenticated" e…

5150383

…rror

Fixed import of HTTPBase class

0ebeb3f

Fix HTTPBase class status code on "Not authenticated" error

54d60db

Fix type in the descr of not_authenticated_status_code for HTTPDigest

a9fcb9a

Fix OpenIdConnect security scheme status code on "Not authenticated…

b9f29b8

…" error

Fix OAuth2 security scheme status code on "Not authenticated" error

ade9d83

Fix import of Literal

2c7b381

YuriiMotov added the bug Something isn't working label Jun 11, 2025

YuriiMotov and others added 3 commits June 11, 2025 19:45

Merge branch 'master' into fix-403-response-code-in-auth-schemes

f253f19

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

1737301

Fix mypy warnings

b1b2578

tiangolo changed the title ~~🐛 Use 401 status code in security classes when credentials missed~~ 🐛 Use 401 status code in security classes when credentials are missing Jun 17, 2025

YuriiMotov mentioned this pull request Jul 4, 2025

HTTPBearer security scheme is returning 403 instead or 401 #10177

Closed

svlandeg linked an issue Aug 27, 2025 that may be closed by this pull request

HTTPBearer security scheme is returning 403 instead or 401 #10177

Closed

cleder approved these changes Aug 28, 2025

View reviewed changes

This comment was marked as resolved.

Sign in to view

github-actions bot added the conflicts Automatically generated when a PR has a merge conflict label Sep 20, 2025

Merge branch 'master' into fix-403-response-code-in-auth-schemes

8c20acb

github-actions bot removed the conflicts Automatically generated when a PR has a merge conflict label Sep 20, 2025

github-actions bot added the conflicts Automatically generated when a PR has a merge conflict label Oct 23, 2025

This comment was marked as resolved.

Sign in to view

Merge branch 'master' into fix-403-response-code-in-auth-schemes

37e47ab

github-actions bot removed the conflicts Automatically generated when a PR has a merge conflict label Oct 24, 2025

tiangolo added 11 commits November 24, 2025 16:54

♻️ Refactor implementation of security schemes to allow subclassing t…

dcd5b16

…o create the exception to be raised

✅ Update tests

f7d88c0

🔥 Remove tests for not_authenticated_status_code parameter, as it's…

64cef34

… refactored into subclassing

♻️ Refactor HTTP security utility classes to simplify them, use the s…

61b4f13

…ame type of error for invalid authentication

✅ Update tests to check the same error for HTTP security utils

3fbf5c9

📝 Update existing tutorials to use the same new error detail

f6bf39b

📝 Add source examples for new docs, for customizing the error for sec…

21750e8

…urity utils

✅ Add tests for the new docs sources

83bd867

📝 Add new docs to override default error status codes

e0a2422

🔧 Update MkDocs config, add new docs

600897d

Merge branch 'master' into fix-403-response-code-in-auth-schemes

f89fef5

tiangolo approved these changes Nov 24, 2025

View reviewed changes

tiangolo added 3 commits November 24, 2025 19:29

✅ Update recent test

8af7b8a

📝 Fix docs include

3e80032

🐛 Fix types for Python 3.8

61d703e

tiangolo merged commit 51ad909 into fastapi:master Nov 24, 2025
45 checks passed

r4victor mentioned this pull request Nov 25, 2025

[Bug]: Tests failing with FastAPI 0.122.0 dstackai/dstack#3317

Closed

GibranAlfa mentioned this pull request Nov 25, 2025

Update test to expect 401 instead of 403 equinor/fmu-settings-api#201

Closed

YuriiMotov mentioned this pull request Dec 1, 2025

Basic auth realm is REQUIRED but handled as optional #13471

Closed

nilslindemann added a commit to nilslindemann/fastapi that referenced this pull request Dec 1, 2025

Sync with fastapi#13786

fe7b7f2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

🐛 Use `401` status code in security classes when credentials are missing #13786

🐛 Use `401` status code in security classes when credentials are missing #13786

Uh oh!

YuriiMotov commented Jun 11, 2025 •

edited

Loading

Uh oh!

bjmc commented Jul 15, 2025 •

edited

Loading

Uh oh!

stg609 commented Aug 6, 2025

Uh oh!

Cito commented Aug 6, 2025

Uh oh!

cleder commented Aug 28, 2025

Uh oh!

cleder left a comment

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

tiangolo left a comment •

edited

Loading

Uh oh!

github-actions bot commented Nov 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

🐛 Use 401 status code in security classes when credentials are missing #13786

🐛 Use 401 status code in security classes when credentials are missing #13786

Uh oh!

Conversation

YuriiMotov commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Warning

Description

Breaking changes and workaround

Changes and reasoning

APIKeyQuery, APIKeyHeader, APIKeyCookie

HTTP Basic

HTTP Digest

HTTP Bearer, OAuth2 schemes, OIDC

Links

Uh oh!

bjmc commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stg609 commented Aug 6, 2025

Uh oh!

Cito commented Aug 6, 2025

Uh oh!

cleder commented Aug 28, 2025

Uh oh!

cleder left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

tiangolo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 24, 2025

📝 Docs preview

Modified Pages

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

🐛 Use `401` status code in security classes when credentials are missing #13786

🐛 Use `401` status code in security classes when credentials are missing #13786

YuriiMotov commented Jun 11, 2025 •

edited

Loading

bjmc commented Jul 15, 2025 •

edited

Loading

tiangolo left a comment •

edited

Loading