docs(auth): complete public API docstrings

Author: leandrodamascena

aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/base.py

@@ -30,6 +30,30 @@ def verify_authorization_header(self, value: str | None) -> dict[str, Any]:
 
         The scheme is case-insensitive. Missing headers, malformed values, and
         schemes other than Bearer raise ``InvalidTokenError``.
+
+        Parameters
+        ----------
+        value : str | None
+            Raw HTTP Authorization header value.
+
+        Returns
+        -------
+        dict[str, Any]
+            Claims after token verification.
+
+        Raises
+        ------
+        InvalidTokenError
+            Header or token is missing, malformed, or invalid.
+        JWKSFetchError
+            Current trusted signing keys could not be obtained.
+
+        Examples
+        --------
+        ```python
+        authorization = event.get("headers", {}).get("authorization")
+        claims = verifier.verify_authorization_header(authorization)
+        ```
         """
         from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.authorization import bearer_token
 

aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/api_gateway.py

@@ -32,6 +32,36 @@ def authorize_event(
     context_claims: list[str] | None,
     on_error: Callable[[AuthError], None] | None,
 ) -> dict[str, Any]:
+    """Build an API Gateway authorizer response after verifying its bearer token.
+
+    Parameters
+    ----------
+    verifier : Verifier
+        Verifier used for the request token.
+    event : dict[str, Any] | DictWrapper
+        API Gateway TOKEN or REQUEST authorizer event.
+    scopes : list[str] | None
+        Scopes required for an Allow response.
+    response_format : Literal["iam", "simple"]
+        IAM policy or HTTP API 2.0 simple response.
+    context_claims : list[str] | None
+        Verified scalar claims copied into authorizer context.
+    on_error : Callable | None
+        Callback notified with a sanitized authentication error.
+
+    Returns
+    -------
+    dict[str, Any]
+        Deny/Allow IAM policy or simple authorization response.
+
+    Raises
+    ------
+    ValueError
+        Event or response configuration is invalid.
+    JWKSFetchError
+        Current trusted signing keys could not be obtained.
+    """
+
     raw = event.raw_event if isinstance(event, DictWrapper) else event
     _validate_event(raw, response_format)
     arn = _request_arn(raw) if response_format == "iam" else None

aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/event_handler.py

@@ -34,6 +34,22 @@ class AuthErrorContext:
 
 
 class AuthMiddleware(BaseMiddlewareHandler[ApiGatewayResolver]):
+    """Event Handler middleware that verifies JWTs before invoking a route.
+
+    Create this middleware with ``Verifier.require()``.
+
+    Parameters
+    ----------
+    verifier : Verifier
+        Verifier used for incoming bearer tokens.
+    scopes : list[str] | None
+        Scopes required by the protected route.
+    authorize : Callable | None
+        Additional policy receiving verified claims.
+    on_error : Callable | None
+        Callback that maps a safe error context to an Event Handler response.
+    """
+
     def __init__(
         self,
         verifier: Verifier,
@@ -47,6 +63,21 @@ def __init__(
         self._on_error = on_error
 
     def handler(self, app: ApiGatewayResolver, next_middleware: NextMiddleware) -> Response:
+        """Verify the request and expose claims while downstream code executes.
+
+        Parameters
+        ----------
+        app : ApiGatewayResolver
+            Resolver handling the current request.
+        next_middleware : NextMiddleware
+            Next middleware or route handler in the chain.
+
+        Returns
+        -------
+        Response
+            Downstream response or an authentication failure response.
+        """
+
         try:
             raw = app.current_event.raw_event
             token = header_token(raw.get("headers"), raw.get("multiValueHeaders"))