Skip to content

Exceptions

Custom exceptions raised by cognito-auth.

InvalidTokenError

InvalidTokenError

Bases: AuthenticationError

Raised when token is invalid or verification fails

Source code in src/cognito_auth/exceptions.py 
 7
 8
 9
10
class InvalidTokenError(AuthenticationError):
    """Raised when token is invalid or verification fails"""

    pass

Raised when a JWT token fails signature verification or is malformed.

Common causes: - Token signature doesn't match public key - Token is malformed or corrupted - Token was not issued by the expected ALB or Cognito User Pool

Example: 

from cognito_auth import User
from cognito_auth.exceptions import InvalidTokenError

try:
    user = User(
        oidc_data_header="invalid-token",
        access_token_header="invalid-token",
        region="eu-west-2",
        verify_tokens=True
    )
except InvalidTokenError as e:
    print(f"Token validation failed: {e}")

ExpiredTokenError

ExpiredTokenError

Bases: AuthenticationError

Raised when token has expired

Source code in src/cognito_auth/exceptions.py 
13
14
15
16
class ExpiredTokenError(AuthenticationError):
    """Raised when token has expired"""

    pass

Raised when a JWT token has expired.

Common causes: - User's session has timed out - Token expiration time (exp claim) is in the past - System clock skew

Example: 

from cognito_auth import User
from cognito_auth.exceptions import ExpiredTokenError

try:
    user = User(
        oidc_data_header=expired_token,
        access_token_header=access_token,
        region="eu-west-2",
        verify_tokens=True
    )
except ExpiredTokenError as e:
    print(f"Token expired: {e}")
    # Redirect user to re-authenticate

MissingTokenError

MissingTokenError

Bases: AuthenticationError

Raised when required token headers are missing

Source code in src/cognito_auth/exceptions.py 
19
20
21
22
class MissingTokenError(AuthenticationError):
    """Raised when required token headers are missing"""

    pass

Raised when required Cognito headers are missing from the request.

Common causes: - Application not behind ALB with OIDC authentication enabled - Headers not properly forwarded by load balancer - Testing without dev mode enabled

Example: 

from cognito_auth import User
from cognito_auth.exceptions import MissingTokenError

try:
    user = User(
        oidc_data_header=None,  # Missing header
        access_token_header="token",
        region="eu-west-2",
        verify_tokens=True
    )
except MissingTokenError as e:
    print(f"Required headers missing: {e}")

Handling Exceptions

Framework auth classes handle these exceptions automatically:

StreamlitAuth: 

# Automatically catches exceptions and calls st.stop()
user = auth.get_auth_user()

DashAuth / FastAPIAuth / GradioAuth: 

# Automatically redirects or raises HTTPException
user = auth.get_auth_user()

Manual handling: 

from cognito_auth import User
from cognito_auth.exceptions import (
    InvalidTokenError,
    ExpiredTokenError,
    MissingTokenError
)

try:
    user = User(
        oidc_data_header=oidc_token,
        access_token_header=access_token,
        region="eu-west-2",
        verify_tokens=True
    )
except MissingTokenError:
    # Redirect to login
    pass
except ExpiredTokenError:
    # Session expired, re-authenticate
    pass
except InvalidTokenError:
    # Tampered or invalid token
    pass