Skip to main content

Initialization

To interact with the AI Engine Manager, you must authenticate first. This guide covers all available authentication methods for different use cases.

Understanding the Clients Object​

The login() function returns a Clients object that provides access to all AI Engine Manager clients:

import h2o_engine_manager

clients = h2o_engine_manager.login()

# View all available clients
print(f"""
Available clients:
  - dai_engine_client:              {clients.dai_engine_client}
  - h2o_engine_client:              {clients.h2o_engine_client}
  - notebook_engine_client:         {clients.notebook_engine_client}
  - dai_engine_profile_client:      {clients.dai_engine_profile_client}
  - h2o_engine_profile_client:      {clients.h2o_engine_profile_client}
  - notebook_engine_profile_client: {clients.notebook_engine_profile_client}
  - dai_engine_version_client:      {clients.dai_engine_version_client}
  - h2o_engine_version_client:      {clients.h2o_engine_version_client}
  - notebook_engine_image_client:   {clients.notebook_engine_image_client}
""")

Output:

Available clients:
  - dai_engine_client:              <h2o_engine_manager.clients.dai_engine.dai_engine_client.DAIEngineClient object at 0x...>
  - h2o_engine_client:              <h2o_engine_manager.clients.h2o_engine.client.H2OEngineClient object at 0x...>
  - notebook_engine_client:         <h2o_engine_manager.clients.notebook_engine.client.NotebookEngineClient object at 0x...>
  - dai_engine_profile_client:      <h2o_engine_manager.clients.dai_engine_profile.client.DAIEngineProfileClient object at 0x...>
  - h2o_engine_profile_client:      <h2o_engine_manager.clients.h2o_engine_profile.client.H2OEngineProfileClient object at 0x...>
  - notebook_engine_profile_client: <h2o_engine_manager.clients.notebook_engine_profile.client.NotebookEngineProfileClient object at 0x...>
  - dai_engine_version_client:      <h2o_engine_manager.clients.dai_engine_version.client.DAIEngineVersionClient object at 0x...>
  - h2o_engine_version_client:      <h2o_engine_manager.clients.h2o_engine_version.client.H2OEngineVersionClient object at 0x...>
  - notebook_engine_image_client:   <h2o_engine_manager.clients.notebook_engine_image.client.NotebookEngineImageClient object at 0x...>

Authentication Methods​

Using H2O Notebook Engine​

If you're running code within an H2O Notebook Engine on H2O AI Cloud, your environment is already configured with the necessary credentials.

import h2o_engine_manager

clients = h2o_engine_manager.login()

This is the simplest method—no additional configuration required.

Using H2O CLI​

For local development, the recommended approach is to use the H2O CLI, which securely manages your credentials.

Step 1: Setup​

  1. Visit the CLI & API Access section in your H2O AI Cloud instance
  2. Download and install the H2O CLI following the provided instructions
  3. Configure your credentials using the CLI

For detailed setup instructions, see Using the H2O CLI in the H2O AI Cloud documentation.

Step 2: Verify Installation​

h2o platform token-info

If configured correctly, this command displays information about your platform token.

Step 3: Basic Usage​

With the H2O CLI configured, you can authenticate without any arguments:

import h2o_engine_manager

clients = h2o_engine_manager.login()

Step 4: (Optional) Custom Configuration Path​

If your H2O CLI configuration file is in a non-standard location, specify the path:

import h2o_engine_manager

clients = h2o_engine_manager.login(
    config_path="/path/to/h2o-cli-config.toml"
)

Note: The default configuration path is ~/.h2oai/h2o-cli-config.toml.

Using Platform Token​

You can authenticate directly with a platform token, which is useful for automation and CI/CD environments.

Step 1: Generating a Platform Token​

  1. Log in to H2O AI Cloud
  2. Navigate to the CLI & API Access section
  3. Click Generate Platform Token
  4. Copy the generated token

Step 2: Usage​

import h2o_engine_manager

clients = h2o_engine_manager.login(
    platform_token="your-platform-token-here"
)

Using Wave App​

For Production Deployments​

For Wave 0.25.2 and Later​

For Wave version 0.25.2 and later when deploying to H2O AI Cloud, use the built-in token refresh capability:

from h2o_wave import app, Q, main
import h2o_engine_manager

@app('/')
async def serve(q: Q):
    clients = await q.run(
        h2o_engine_manager.login,
        token_provider=q.auth.ensure_fresh_token_sync,
    )
    
    # Use the clients
    engines = clients.dai_engine_client.list_engines()
tip

Wave 0.25.2 and later versions include q.auth.ensure_fresh_token_sync, which automatically handles token refresh for you.

For Older Wave Versions​

For older Wave versions, you must manually create the token provider using the h2o_authn package:

import os
from h2o_wave import app, Q
import h2o_engine_manager
import h2o_authn

@app('/')
async def serve(q: Q):
    # Create token provider from Wave's authentication context
    provider = h2o_authn.TokenProvider(
        refresh_token=q.auth.refresh_token,
        issuer_url=os.getenv("H2O_WAVE_OIDC_PROVIDER_URL"),
        client_id=os.getenv("H2O_WAVE_OIDC_CLIENT_ID"),
        client_secret=os.getenv("H2O_WAVE_OIDC_CLIENT_SECRET"),
    )

    # Login with the token provider
    clients = await q.run(h2o_engine_manager.login, token_provider=provider)
    
    # Use the clients
    engines = clients.dai_engine_client.list_engines()
info

The h2o_authn package is automatically available in H2O AI Cloud Wave apps. For more information, see the h2o_authn package documentation.

Thread Safety

For multiuser Wave apps, authentication and client operations are already thread-safe. The example above works correctly for concurrent users.

For Local Development​

When developing Wave apps locally, you can use the H2O CLI configuration. This allows h2o_engine_manager.login() to obtain credentials from your local H2O CLI profile, assuming you are logged in via h2o login:

import h2o_engine_manager
from h2o_wave import app, Q

@app('/')
async def serve(q: Q):
    # During local development, credentials are sourced from your local H2O CLI configuration
    clients = h2o_engine_manager.login()
    
    # Use the clients as needed
    engines = clients.dai_engine_client.list_engines()
info

Make sure you have logged in to the H2O CLI (via h2o login) and have a valid credentials file in your home directory. See H2O CLI docs for more details.

Using Custom OIDC Configuration​

For advanced use cases such as custom deployments, testing, or for use outside of H2O AI Cloud, use the login_custom() function to manually specify OIDC and endpoint parameters:

import h2o_engine_manager

clients = h2o_engine_manager.login_custom(
    endpoint="https://enginemanager.cloud.h2o.ai",
    refresh_token="your-oidc-refresh-token",
    issuer_url="https://auth.cloud.h2o.ai/auth/realms/hac",
    client_id="your-oidc-client-id",
    client_secret="your-oidc-client-secret",  # Optional, supply if your client requires it
    # optional:
    # default_workspace_id="your-workspace-id",
    # verify_ssl=True,
    # ssl_ca_cert="/path/to/ca-bundle.pem"
)

Parameters​

  • endpoint (required): The AI Engine Manager service URL (e.g., https://enginemanager.cloud.h2o.ai)
  • refresh_token (required): Your OIDC refresh token
  • issuer_url (required): The OIDC issuer URL
  • client_id (required): The OIDC client ID
  • client_secret (optional): The OIDC client secret, if required
  • default_workspace_id (optional): Which workspace to use by default ("default" if not specified)
  • verify_ssl (optional): Boolean for SSL verification (True by default)
  • ssl_ca_cert (optional): Path to a CA bundle for SSL verification, if needed

Advanced Configuration​

Specifying the Environment​

You can explicitly specify the H2O AI Cloud environment:

import h2o_engine_manager

clients = h2o_engine_manager.login(
    environment="https://cloud.h2o.ai"
)

This is useful when working with multiple H2O AI Cloud environments.

Setting a Default Workspace​

To set a default workspace for all operations:

import h2o_engine_manager

clients = h2o_engine_manager.login(
    default_workspace_id="my-workspace-id"
)

The default workspace ID is "default", which refers to your personal workspace.

SSL Configuration​

For environments with custom SSL certificates or when SSL verification needs to be disabled:

import h2o_engine_manager

# Use a custom CA certificate bundle
clients = h2o_engine_manager.login(
    ssl_ca_cert="/path/to/ca-bundle.pem"
)

# Disable SSL verification (not recommended for production)
clients = h2o_engine_manager.login(
    verify_ssl=False
)
Feedback