Skip to content

feat: add AuthServerUnavailableError for discovery and JWKS fetch failures - #148

Merged
kishore7snehil merged 2 commits into
mainfrom
feat/auth-server-unavailable-error
Oct 23, 2026
Merged

kishore7snehil merged 2 commits into
mainfrom
feat/auth-server-unavailable-error

Conversation

@kishore7snehil

@kishore7snehil kishore7snehil commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

📋 Changes

This PR adds AuthServerUnavailableError, raised when the OIDC discovery document or the JWKS cannot be reached while verifying an access token. Callers can now tell an outage on the authorization server side apart from a token that was rejected, so a good token is not reported as invalid.

✨ Features

  • New Error: AuthServerUnavailableError subclasses VerifyAccessTokenError, with status 503 and error code auth_server_unavailable. Existing except VerifyAccessTokenError handlers still catch it.
  • No Challenge Header: verify_request() sets no WWW-Authenticate header on this error, so clients retry later instead of requesting a new token.
  • Both Entry Points: verify_access_token() and verify_request() (Bearer and DPoP) raise the new error.

🔧 API Changes

  • Exported AuthServerUnavailableError from the package root.
  • A discovery or JWKS fetch that cannot be reached (connection error, timeout, or an HTTP 5xx or 429 response) now raises AuthServerUnavailableError with status 503. It previously raised VerifyAccessTokenError with status 401. Other fetch failures, such as a 404 or a malformed response, still raise VerifyAccessTokenError.
  • Errors with a status of 500 or above no longer get a WWW-Authenticate header from verify_request().
  • Added the new error to the Raises sections of verify_request(), verify_access_token(), get_access_token_for_connection() and get_token_on_behalf_of().

📖 Documentation

  • Updated README.md to describe the new error under "Verify the Access Token"
  • Added "Telling an Outage from an Invalid Token" to EXAMPLES.md
  • Added a note to the error handling section of docs/MultipleCustomDomain.md

🧪 Testing

  • This change adds test coverage
  • This change has been tested on the latest version of the platform/language

Contributor Checklist

@kishore7snehil
kishore7snehil requested a review from a team as a code owner October 23, 2026 05:41
Comment thread src/auth0_api_python/api_client.py Resolved
Comment thread README.md Resolved
Comment thread src/auth0_api_python/api_client.py Resolved
Comment thread tests/test_api_client.py Resolved
Discovery and JWKS fetch failures raise AuthServerUnavailableError only for connection errors, timeouts, HTTP 5xx and HTTP 429. Other failures keep raising VerifyAccessTokenError.
@kishore7snehil
kishore7snehil merged commit 551db02 into main Oct 23, 2026
7 checks passed
@kishore7snehil
kishore7snehil deleted the feat/auth-server-unavailable-error branch October 23, 2026 12:09
@kishore7snehil kishore7snehil mentioned this pull request Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants