API Key Authentication
----------------------

API Key Authentication typically involves clients sending a unique API key with
each request, often in a header or as a query parameter. Similar to
Basic Authentication, it does not involve the dynamic exchange of tokens,
limiting the applicability of token-specific hooks.

**Applicable Hooks**:

*   ``get_secret_keys``: To add sensitive credential fields to mask in logs.
*   ``modify_session``: To add the API key to the appropriate HTTP header or query
    parameter for authenticated requests.


The most common method of sending the API key is in a header and this is
currently supported by the out of the box API Key Authenticator as defined
in the :ref:`API Key Auth <apikey-authenticator>` section. However the API key can
also be in the query parameters. The following examples show how they can be
easily supported.

API Key in Query parameter
^^^^^^^^^^^^^^^^^^^^^^^^^^

The following example shows how the ``modify_session`` hook can be used to
support cases where the key should be sent in a query parameter. In this case
the example will be to access the FRED database. The following is an example of
a url call: ``https://api.stlouisfed.org/fred/series/observations?series_id=GNPCA&api_key=*****&file_type=json``

Notice that query parameters of ``api_key=*****`` and the ``file_type=json`` are
required parameters. The existing Universal Credential in Low-code Tools can be
leveraged. In this case, the API Key Authentication mechanism is selected, the
url is entered, and the key is entered in the API key field.

.. note::
    The Authorization Header field in the credential should be set to `Authorization`.

In order to support this, the ``modify_session`` hook is used to add those
parameters. For this case, the existing credential in Low-code Tools was used.
It is important to note that in the credential there is a field called
``Authenticator Override``. That field **must** be populated with the name of your
authenticator. (In this case it is ``FREDApiKeyAuth``).

Ideally, there is only a single line of code that needs to be created and this
is shown as follows:
``session.params = {'api_key':auth_info['Authorization'],'file_type':'json'}``
The above statement adds two params to the api call with the first being
``api_key:*****`` where ``*****`` is the ``api_key`` that was entered in the
`Authorization Header` credential field.

.. note::
    Authenticators make use of session properties extensively. See `Request Sessions
    <https://requests.readthedocs.io/en/latest/api/#request-sessions>`_ for all
    the session properties.

.. code-block:: python

    from silo.apps.errors import error_manager
    with error_manager(self):

        from silo.low_code import *
        from silo.apps.collection import create_collections, save_collections

        # =====================================
        # =========== User Editable ===========
        # =====================================
        # List any custom substitutions that need to occur within the snippet arguments
        from silo.auth import create_api_key_authenticator

        custom_substitution = {}

        def modify_session_hook(session, auth_info):
            session.params = {'api_key':auth_info['Authorization'],'file_type':'json'}

        create_api_key_authenticator(
            name="FREDApiKeyAuth",
            description="A configurable API Key authenticator usable for testing.",
            modify_session=modify_session_hook,
        )

        # =====================================
        # ========= End User Editable =========
        # =====================================


        collections = create_collections(self)
        snippet_framework(collections, custom_substitution, snippet_id, app=self)
        save_collections(collections, self)