Authentication

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

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):

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:

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.

Synchronous client:

from h2ogpte import H2OGPTE

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

Async client:

from h2ogpte import H2OGPTEAsync

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

WebSocket client (SharedH2OGPTEClient):

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:

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

If you provide none, the client raises:

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.