Skip to main content

API authentication

In addition to the H2O AI Cloud UI, this platform comes with APIs for running AI engines, training models, deploying these models to production, running AI apps, and more. The H2O AI Cloud platform token lets you securely obtain your OpenID Connect (OIDC) access tokens, which are needed to use these APIs.

Similar to a traditional API token, the platform token lets you orchestrate HAIC APIs from your local workstation, Jupyter notebooks, or a wide variety of other environments. This page describes the HAIC platform token, its specifics, and how to leverage it.

info

The platform token must be enabled in the environment for the following steps to work. If you have issues replicating the following steps, contact your administrator to enable it.

Getting the platform token​

You will need your platform token to connect to any of the H2O AI Cloud APIs. You can access this token any time you need it either by using the H2O AI Cloud UI, or by using the command line tool in your favorite terminal. Both options are detailed below.

note

HAIC platform tokens do not currently have an expiration mechanism.

If you have set up and configured the H2O CLI, you can obtain the token by running:

$ h2o config update-platform-token

Visit https://<HAIC URL>/auth/get-platform-token to generate a new token and paste it below:
Token:

You will be prompted to visit the provided URL to generate a token and then provide the token value that you obtained.

Next, you can get additional necessary information about the token by running:

$ h2o platform token-info
Token Endpoint URL  <OIDC token endpoint URL>
Client ID           <OIDC client id>
Refresh Token       <your platform token>

Alternatively, follow the instructions given on the UI at https://<HAIC URL>/cli-and-api-access. For more information on how to access this UI screen on your HAIC instance, see Configuring the CLI.

info

The platform token is as sensitive as your username and password! Using this, applications can log into the H2O AI Cloud as you. Protect your account by avoiding the use of the platform token directly in your code base or notebooks. Instead, consider using tools such as getpass or os.environ to use the platform token without having it unprotected in your code or notebooks.

Authenticate using the h2o-authn package​

The h2o-authn package is a Python package that simplifies the authentication process. It's a universal token provider library that can be used with various H2O.ai Python client libraries.

For information about installing and using the h2o-authn package, see the PyPI project description.

After installing the h2o-authn package, update the h2o_ai_cloud.py file with the connection parameters listed in the Accessing H2O AI Cloud APIs section on the CLI & API access information page.

To find out the specific values of the connection parameters according to your environment, click on your username on the top-right corner of the App Store home screen, and click CLI & API access.

cli-and-api-access

You will see the following screen with the generated values for Endpoint URL, OIDC URL, and Client ID.

cli-generated-values

The following code snippet is an example of how you can use h2o-authn within a Python script. Replace the TOKEN ENDPOINT and the CLIENT ID values within the code snippet, with the values received from the CLI and API access page.

h2o_ai_cloud.py
import getpass

import h2o_authn
import h2o_mlops_client
import h2osteam

# The URL you use to access the H2O AI Cloud's UI - do not include the `https://` - ex: cloud.h2o.ai
H2O_CLOUD_URL = "cloud.h2o.ai"

# Information available at https://cloud.h2o.ai/cli-and-api-access
TOKEN_ENDPOINT = "https://auth.cloud.h2o.ai/auth/realms/hac/protocol/openid-connect/token"
API_CLIENT_ID = "hac-platform-public"
REFRESH_TOKEN_URL = "https://cloud.h2o.ai/auth/get-platform-token"

def token_provider():
    """Connect to the H2O AI Cloud
    If these notebooks are running within a HAIC environment, the os variables will exist automatically as App Secrets.
    When running these notebooks locally, you can update these variables based on the values in the CLI & API Acess page by clicking on your name from the H2O AI Cloud UI.
    """
    
    print(f"Visit {REFRESH_TOKEN_URL} to get your platform token")

    return h2o_authn.TokenProvider(
        refresh_token=getpass.getpass("Enter your platform token: "),
        client_id=API_CLIENT_ID,
        token_endpoint_url=TOKEN_ENDPOINT,
    )

def mlops_client():
    """Connects to MLOps."""
    MLOPS_API = "https://mlops-api." + H2O_CLOUD_URL
    
    return h2o_mlops_client.Client(
        gateway_url=MLOPS_API,
        token_provider=token_provider(),
    )

def steam_client():
    """Connect to Enterprise Steam, Driverless AI, and H2O-3"""
    tp = token_provider()
    STEAM_API = "https://steam." + H2O_CLOUD_URL
    
    return h2osteam.login(
        url=STEAM_API,
        access_token=tp(),
    )
Feedback