ds_stoa.authentication
======================

.. py:module:: ds_stoa.authentication

.. autoapi-nested-parse::

   This module provides authentication and RESTful API interaction capabilities for the Stoa API.

   It includes two primary functions:

   - **oauth2**: For obtaining OAuth2 authentication tokens necessary for secure API access. This function uses client ID and client secret to authenticate.
   - **rest**: For making authenticated RESTful API requests to various endpoints within the Stoa API. This function uses email and password for authentication, differing from the `oauth2` method which uses client credentials.

   These functions facilitate secure and efficient communication with the Stoa API,
   enabling the exchange of data through authenticated requests.

   **Example usage**::

       from ds_stoa.authentication import oauth2, rest

       token = oauth2(
           client_id="your_client_id",
           client_secret="your_client_secret",
       )

       token = rest(
           email="your_email",
           password="your_password",
       )



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/ds_stoa/authentication/_oauth2/index
   /autoapi/ds_stoa/authentication/_rest/index


Functions
---------

.. autoapisummary::

   ds_stoa.authentication.oauth2
   ds_stoa.authentication.rest


Package Contents
----------------

.. py:function:: oauth2(client_id: str, client_secret: str) -> str

   Authenticates an application and retrieves an access token.

   :param client_id: The Client ID.
   :type client_id: str
   :param client_secret: The Client Secret.
   :type client_secret: str
   :returns: An access token indicating successful authentication.
   :rtype: str

   **Example**::

       >>> oauth2('client_id', 'client_secret')
       'access_token_value'


.. py:function:: rest(email: str, password: str) -> str

   Authenticates a user and retrieves an access token.

   :param email: The email of the user.
   :type email: str
   :param password: The password of the user.
   :type password: str
   :returns: An access token indicating successful authentication.
   :rtype: str

   **Example**::

       >>> rest('user@example.com', 'secret')
       'access_token_value'