{"id":9802,"library":"h2o-authn","title":"H2O Python Clients Authentication Helpers","description":"h2o-authn provides authentication helpers for H2O.ai Python clients, simplifying secure interactions with H2O AI Cloud and other services. It primarily focuses on managing and refreshing access tokens using various authentication flows, such as Client Credentials. The current version is 3.1.0, and the library maintains an active development pace with several releases per year.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/h2oai/authn-py","tags":["authentication","h2o.ai","oauth2","client credentials","token","async"],"install":[{"cmd":"pip install h2o-authn","lang":"bash","label":"Install stable version"},{"cmd":"pip install \"h2o-authn[discovery]\"","lang":"bash","label":"Install with discovery feature"}],"dependencies":[{"reason":"Required for HTTP requests to authentication endpoints.","package":"httpx","optional":false},{"reason":"Required for Python versions < 3.10 for backport of typing features.","package":"typing_extensions","optional":false},{"reason":"Optional dependency for using token providers created from discovery objects.","package":"h2o-cloud-discovery","optional":true}],"imports":[{"symbol":"ClientCredentialsTokenProvider","correct":"from h2o_authn import ClientCredentialsTokenProvider"},{"symbol":"AuthCache","correct":"from h2o_authn import AuthCache"},{"note":"Commonly nested exceptions are imported from their specific module path.","wrong":"from h2o_authn import TokenEndpointError","symbol":"TokenEndpointError","correct":"from h2o_authn.auth.token_provider import TokenEndpointError"}],"quickstart":{"code":"import os\nimport httpx\nimport asyncio\nfrom h2o_authn import ClientCredentialsTokenProvider, AuthCache\n\nasync def authenticate_and_get_token():\n    auth_url = os.environ.get(\"H2O_AUTHN_URI\", \"\")\n    client_id = os.environ.get(\"H2O_AUTHN_CLIENT_ID\", \"\")\n    client_secret = os.environ.get(\"H2O_AUTHN_CLIENT_SECRET\", \"\")\n\n    if not all([auth_url, client_id, client_secret]):\n        print(\"Please set H2O_AUTHN_URI, H2O_AUTHN_CLIENT_ID, and H2O_AUTHN_CLIENT_SECRET environment variables.\")\n        return\n\n    async with httpx.AsyncClient() as client:\n        token_provider = ClientCredentialsTokenProvider(\n            auth_url=auth_url,\n            client_id=client_id,\n            client_secret=client_secret,\n            client=client,\n        )\n\n        # Optional: Wrap with AuthCache for token caching and refresh\n        cached_token_provider = AuthCache(token_provider)\n\n        try:\n            token = await cached_token_provider.get_token()\n            print(f\"Successfully obtained token. Access Token (first 10 chars): {token.access_token[:10]}...\")\n            print(f\"Token expires in: {token.expires_in} seconds\")\n        except Exception as e:\n            print(f\"Authentication failed: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(authenticate_and_get_token())\n","lang":"python","description":"This quickstart demonstrates how to use `h2o-authn` to obtain an access token using the Client Credentials flow. It fetches authentication details from environment variables (H2O_AUTHN_URI, H2O_AUTHN_CLIENT_ID, H2O_AUTHN_CLIENT_SECRET), initializes a `ClientCredentialsTokenProvider` with an `httpx.AsyncClient`, and then retrieves a token. It also shows wrapping the provider with `AuthCache` for automatic token caching and refreshing."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer, or pin `h2o-authn<3.0.0` if you must remain on Python 3.8.","message":"Python 3.8 is no longer officially supported as of version 3.0.0. Projects using `h2o-authn` 3.x or later must run on Python 3.9 or newer.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure `httpx>=0.23.0` is installed in your environment. If other dependencies require an older `httpx` version, you may face conflicts requiring careful dependency management or pinning `h2o-authn<3.0.0`.","message":"The minimum required version of the `httpx` library was updated to `0.23.0` in `h2o-authn` v3.0.0. Older versions of `httpx` may cause dependency conflicts or runtime errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Python environment to 3.8 or newer. For `h2o-authn>=3.0.0`, Python 3.9+ is required.","message":"Python 3.7 support was dropped in `h2o-authn` v2.0.0. Using this library with Python 3.7 is no longer supported and may lead to installation failures or unexpected behavior.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Always ensure the necessary environment variables are set correctly before running applications that use `h2o-authn`. Use `os.environ.get('VAR', '')` for safer access in code.","message":"The library heavily relies on environment variables (`H2O_AUTHN_URI`, `H2O_AUTHN_CLIENT_ID`, `H2O_AUTHN_CLIENT_SECRET`) for configuration. Missing or incorrectly set variables will lead to `RuntimeError` or `TokenEndpointError` at runtime.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Set the missing environment variable. For example: `export H2O_AUTHN_CLIENT_ID=\"your_client_id\"`.","cause":"One of the required environment variables (H2O_AUTHN_URI, H2O_AUTHN_CLIENT_ID, H2O_AUTHN_CLIENT_SECRET) for token provider initialization is not set.","error":"RuntimeError: Missing environment variable: H2O_AUTHN_CLIENT_ID"},{"fix":"Verify that `H2O_AUTHN_URI`, `H2O_AUTHN_CLIENT_ID`, and `H2O_AUTHN_CLIENT_SECRET` are all correct and correspond to a valid H2O AI Cloud instance or authentication service.","cause":"The authentication request to the provided `H2O_AUTHN_URI` failed, typically due to incorrect client ID, client secret, or an invalid authentication endpoint.","error":"h2o_authn.auth.token_provider.TokenEndpointError: Authentication request failed (status: 401 Unauthorized)"},{"fix":"Install the library using pip: `pip install h2o-authn`.","cause":"The `h2o-authn` library is not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'h2o_authn'"},{"fix":"Import the class directly from the top-level package: `from h2o_authn import ClientCredentialsTokenProvider`.","cause":"Attempting to import a class directly from a submodule when it's exposed at the top-level package or vice versa. The specified class is typically available directly under `h2o_authn`.","error":"ImportError: cannot import name 'ClientCredentialsTokenProvider' from 'h2o_authn.auth.token_provider'"}]}