Authentication
==============

The ``h2ogpte`` Python client supports three mutually exclusive authentication
methods. Provide exactly one when you create a client instance.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Parameter
     - Description
   * - ``api_key``
     - h2oGPTe API key (most common method).
   * - ``token_provider``
     - Token provider that supplies a bearer token.
   * - ``azure_token``
     - Azure Entra ID access token. Sent using the ``Bearer-AD`` authorization scheme.

.. note::

   ``SharedH2OGPTEClient`` (WebSocket client) supports ``api_key`` and
   ``azure_token`` only. ``token_provider`` isn't available for the WebSocket
   client.

API key
-------
Use an API key issued from the h2oGPTe UI (**Settings** > **API Keys**):

.. code-block:: python

    from h2ogpte import H2OGPTE

    client = H2OGPTE(
        address="https://h2ogpte.genai.h2o.ai",
        api_key=API_KEY,
    )

Token provider
--------------
Pass a ``token_provider`` that supplies a bearer token for each request. Use
this method when tokens are short-lived and must be refreshed:

.. code-block:: python

    from h2ogpte import H2OGPTE

    client = H2OGPTE(
        address="https://h2ogpte.genai.h2o.ai",
        token_provider=my_token_provider,
    )

Azure Entra ID
--------------
Use Azure Entra ID (formerly Azure Active Directory) when your organization
manages identity through Azure Entra ID and you want to authenticate
programmatically without an API key. When you provide ``azure_token``, the
client sends your token with the ``Bearer-AD`` authorization scheme on every
request.

To get an access token, follow your organization's Azure Entra ID token
acquisition process, or see the
`Microsoft identity platform documentation <https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow>`__.

Synchronous client:

.. code-block:: python

    from h2ogpte import H2OGPTE

    client = H2OGPTE(
        address="https://YOUR_H2OGPTE_URL",
        azure_token=AZURE_TOKEN,
    )

Async client:

.. code-block:: python

    from h2ogpte import H2OGPTEAsync

    client = H2OGPTEAsync(
        address="https://YOUR_H2OGPTE_URL",
        azure_token=AZURE_TOKEN,
    )

WebSocket client (``SharedH2OGPTEClient``):

.. code-block:: python

    from h2ogpte.shared_client import SharedH2OGPTEClient

    client = SharedH2OGPTEClient(
        address="https://YOUR_H2OGPTE_URL",
        azure_token=AZURE_TOKEN,
    )

After you initialize the client, use it the same way you would with API key
authentication. The ``azure_token`` parameter only changes how the client
authenticates.

.. note::

   The client sends the ``azure_token`` value as-is on every request and does
   not refresh it. If your token expires, create a new client instance with a
   fresh token. For automatic token refresh, use ``token_provider`` instead
   (available on ``H2OGPTE`` and ``H2OGPTEAsync``).

Authentication errors
---------------------
``api_key``, ``token_provider``, and ``azure_token`` are mutually exclusive.
If you provide more than one, the client raises a ``RuntimeError``:

.. code-block:: text

    RuntimeError: api_key, token_provider, and azure_token are mutually exclusive. Please provide exactly one.

If you provide none, the client raises:

.. code-block:: text

    RuntimeError: Please use either an API key, a Token provider, or an Azure token to authenticate.

.. note::

   The exact error text varies by client class. ``SharedH2OGPTEClient``
   references only ``api_key`` and ``azure_token`` in its error messages.