apifrom.security.auth
=====================


Authentication decorators for APIFromAnything.

This module provides decorators for securing API endpoints with various
authentication methods, including JWT, API key, basic auth, and OAuth2.



.. py:currentmodule:: apifrom.security.auth

Overview
--------

**Classes**

* :py:class:`ErrorResponse`


**Functions**

* :py:func:`_get_api_key`
* :py:func:`_get_auth_header`
* :py:func:`_get_basic_auth`
* :py:func:`_get_bearer_token`
* :py:func:`api_key_required`
* :py:func:`basic_auth_required`
* :py:func:`jwt_required`
* :py:func:`oauth2_required`





Classes
-------

.. py:class:: ErrorResponse(message, status_code = 400, error_code = None, details = None, headers = None):bases: JSONResponse


Error response for APIFromAnything.

   This class represents an HTTP error response with JSON content.

   Initialize a new ErrorResponse instance.

   :param message: The error message.
   :param status_code: The HTTP status code.
   :param error_code: An optional error code.
   :param details: Additional error details.
   :param headers: HTTP headers.























Functions
---------

.. py:function:: _get_api_key(request)


Get the API key from a request.

   The API key can be provided in the X-API-Key header or as a query parameter.

   :param request: The request to get the API key from.

   :returns: The API key, or None if not present.


.. py:function:: _get_auth_header(request)


Get the Authorization header from a request.

   :param request: The request to get the header from.

   :returns: The Authorization header value, or None if not present.


.. py:function:: _get_basic_auth(request)


Get the Basic auth credentials from a request.

   :param request: The request to get the credentials from.

   :returns: A tuple of (username, password), or None if not present.


.. py:function:: _get_bearer_token(request)


Get the Bearer token from a request.

   :param request: The request to get the token from.

   :returns: The Bearer token, or None if not present.


.. py:function:: api_key_required(func=None, *, api_keys = None, scopes = None, error_message = 'Invalid or missing API key')


Decorator to require a valid API key for an API endpoint.

   :param func: The function to decorate.
   :param api_keys: A dictionary of API keys and their scopes. If None, uses the API instance's API keys.
                    The values can be strings, lists of strings, or dictionaries with a 'scopes' key.
   :param scopes: A list of scopes that the API key must have.
   :param error_message: The error message to return if the API key is invalid.

   :returns: The decorated function.


.. py:function:: basic_auth_required(func=None, *, credentials = None, error_message = 'Invalid or missing credentials')


Decorator to require valid Basic auth credentials for an API endpoint.

   :param func: The function to decorate.
   :param credentials: A dictionary of username-password pairs. If None, uses the API instance's Basic auth credentials.
   :param error_message: The error message to return if the credentials are invalid.

   :returns: The decorated function.


.. py:function:: jwt_required(func=None, *, secret = None, algorithm = None, verify_exp = True, verify_aud = False, audience = None, verify_iss = False, issuer = None, verify_sub = False, subject = None, required_claims = None, optional_claims = None, error_message = 'Invalid or missing JWT token')


Decorator that requires a valid JWT token for accessing the endpoint.

   :param secret: The secret key used to decode the JWT token
   :param algorithm: The algorithm used to decode the JWT token
   :param verify_exp: Whether to verify the expiration time
   :param verify_aud: Whether to verify the audience
   :param audience: The expected audience
   :param verify_iss: Whether to verify the issuer
   :param issuer: The expected issuer
   :param verify_sub: Whether to verify the subject
   :param subject: The expected subject
   :param required_claims: List of claims that must be present in the token
   :param optional_claims: List of claims that may be present in the token
   :param error_message: The error message to return if the token is invalid

   :returns: The decorated function


.. py:function:: oauth2_required(func=None, *, scopes = None, token_url = None, error_message = 'Invalid or missing OAuth2 token')


Decorator to require a valid OAuth2 token for an API endpoint.

   This is a placeholder implementation. In a real application, you would
   integrate with an OAuth2 provider like Auth0, Okta, or your own OAuth2 server.

   :param func: The function to decorate.
   :param scopes: A list of scopes that the token must have.
   :param token_url: The URL for obtaining tokens.
   :param error_message: The error message to return if the token is invalid.

   :returns: The decorated function.