Authentication and configuration

Every request to the HiddenLayer API must be authenticated, and it must go to the correct regional API host. This page explains how the SDK gets your credentials, how it decides where to send requests, and which client options you can change.

Authentication methods

The SDK supports two ways to authenticate. Configure only one of them.

Method	Credentials	When to use it
OAuth2 client credentials (recommended)	Client ID and client secret	Services, scripts, CI/CD pipelines, and most other cases. The SDK obtains and refreshes tokens for you.
Bearer token	A pre-issued access token	You already obtain tokens through another system and want to pass one in directly.

OAuth2 client credentials

OAuth2 client credentials is a standard flow in which an application authenticates as itself by exchanging a client ID and client secret for a short-lived access token. You create the client ID and client secret in the HiddenLayer Console. See Create API Key. When you provide a client ID and client secret, the SDK handles the token for you:

Before the first API request, the client sends a POST request to {base_url}/oauth2/token with grant_type=client_credentials, authenticating with your client ID and client secret using HTTP Basic authentication.
The client caches the returned access token and adds it to each request as an Authorization: Bearer <token> header.
The client refreshes the token shortly before it expires, based on the expires_in value in the token response (3600 seconds if the response does not include it). Token handling is thread-safe.
If the API returns 401 Unauthorized because the cached token expired, the client discards the token, gets a new one, and retries the request.

Because the token URL is built from the base URL, your credentials must belong to the same region as the base URL. A prod-eu API key does not work against the prod-us host.

If the token request fails, the SDK does not raise an error at that point. It sends the API request without a token, and the API responds with 401, which the SDK raises as AuthenticationError. If you see AuthenticationError, check your client ID, client secret, and region.

Bearer token

If you already have an access token, provide it as a bearer token with the HIDDENLAYER_TOKEN environment variable or the bearer_token argument. The SDK sends it as Authorization: Bearer <token> and does not refresh it. When the token expires, requests fail with AuthenticationError until you supply a new one.

If you configure both a bearer token and a client ID and client secret, the OAuth2 flow overwrites the bearer token’s Authorization header. Configure only one method to avoid confusion.

If you configure neither, the client is still created, but requests are sent without credentials and fail with AuthenticationError.

Environment variables

The client reads these environment variables when you create it. Arguments that you pass to the constructor take precedence over environment variables.

Variable	Purpose	Example value
`HIDDENLAYER_CLIENT_ID`	Client ID for OAuth2 client credentials. Used as `client_id`.	Your client ID
`HIDDENLAYER_CLIENT_SECRET`	Client secret for OAuth2 client credentials. Used as `client_secret`.	Your client secret
`HIDDENLAYER_TOKEN`	Pre-issued bearer token. Used as `bearer_token`.	An access token
`HIDDENLAYER_BASE_URL`	Base URL for all requests. Use it for self-hosted deployments or a local container.	`http://localhost:8000`
`HIDDENLAYER_CUSTOM_HEADERS`	Extra HTTP headers added to every request, one `Name: value` pair per line. Headers passed in `default_headers` win on conflict.	`X-Team: ml-platform`
`HIDDENLAYER_LOG`	Enables SDK logging. Set to `info` or `debug`.	`info`

HIDDENLAYER_LOG=debug logs request options, including JSON request bodies. These can contain prompts, model outputs, and other sensitive data. Do not enable debug logging in production or anywhere logs are shared. See Security and production guidance.

Set environment variables

Set your credentials in the terminal session that runs your code:

macOS/Linux
Windows

export HIDDENLAYER_CLIENT_ID="your-client-id"
export HIDDENLAYER_CLIENT_SECRET="your-client-secret"

$env:HIDDENLAYER_CLIENT_ID = "your-client-id"
$env:HIDDENLAYER_CLIENT_SECRET = "your-client-secret"

Replace the placeholder values with your own. These commands set the variables only for the current terminal session. In production, use your platform’s secret management, such as CI/CD secrets, a container orchestrator’s secrets, or a cloud secret manager, to inject the variables at runtime.

Typing a secret on the command line can save it in your shell history. For local development, a .env file (described next) avoids this.

Optional: use a .env file

A .env file is a plain text file of NAME=value lines that you keep in your project folder. The SDK does not read .env files on its own. You can load one with the third-party python-dotenv package.

Install python-dotenv

python -m pip install python-dotenv

Create a .env file

.env

HIDDENLAYER_CLIENT_ID=your-client-id
HIDDENLAYER_CLIENT_SECRET=your-client-secret

Keep the file out of version control

Add .env to your .gitignore file so that you never commit your secret:

.gitignore

.env

Load the file before you create the client

from dotenv import load_dotenv
from hiddenlayer import HiddenLayer

load_dotenv()  # Copies values from .env into os.environ.

client = HiddenLayer()

Call load_dotenv() before you create the client, because the client reads environment variables only when it is constructed.

Choose a region or base URL

The base URL is the root address that the client sends every request to, for example https://api.us.hiddenlayer.ai. HiddenLayer provides two SaaS environments (regions):

`environment` value	Base URL
`prod-us` (default)	`https://api.us.hiddenlayer.ai`
`prod-eu`	`https://api.eu.hiddenlayer.ai`

Select the EU region with the environment argument:

from hiddenlayer import HiddenLayer

client = HiddenLayer(environment="prod-eu")

An unknown value, such as environment="eu", raises ValueError: Unknown environment: eu.

How the client resolves the base URL

The client picks the base URL in this order and uses the first match:

The base_url argument, if you pass one.
The environment argument, if you pass one.
The HIDDENLAYER_BASE_URL environment variable, if it is set.
The prod-us environment.

If you pass environment while HIDDENLAYER_BASE_URL is also set, the client cannot tell which one you intend and raises:

ValueError: Ambiguous URL; The `HIDDENLAYER_BASE_URL` env var and the `environment` argument are given. If you want to use the environment, you must pass base_url=None

To fix it, unset HIDDENLAYER_BASE_URL, remove the environment argument, or pass base_url=None together with environment to confirm that you want the environment:

from hiddenlayer import HiddenLayer

client = HiddenLayer(environment="prod-eu", base_url=None)

Pass credentials explicitly

By default, the client reads credentials from environment variables. You can also pass them as constructor arguments, for example when your application loads secrets from a secret manager under different names. Read the values from your secret store or the environment. Never write them as literals in code.

import os

from hiddenlayer import HiddenLayer

client = HiddenLayer(
    client_id=os.environ["HIDDENLAYER_CLIENT_ID"],
    client_secret=os.environ["HIDDENLAYER_CLIENT_SECRET"],
    environment="prod-us",
)

To use a bearer token instead:

import os

from hiddenlayer import HiddenLayer

client = HiddenLayer(bearer_token=os.environ["HIDDENLAYER_TOKEN"])

Do not hard-code client secrets or tokens in source files, notebooks, or container images. Anyone with access to the code can use them, and secrets committed to version control remain in the history. If a secret is exposed, delete the API key in the Console and create a new one.

Client options

All constructor arguments are keyword-only. The same arguments work for HiddenLayer and AsyncHiddenLayer.

Option	Default	Description
`client_id`	`HIDDENLAYER_CLIENT_ID`	Client ID for OAuth2 client credentials.
`client_secret`	`HIDDENLAYER_CLIENT_SECRET`	Client secret for OAuth2 client credentials.
`bearer_token`	`HIDDENLAYER_TOKEN`	Pre-issued bearer token.
`environment`	`"prod-us"`	`"prod-us"` or `"prod-eu"`.
`base_url`	Resolved as described in How the client resolves the base URL	Root URL for all requests.
`timeout`	60 seconds total, 5 seconds to connect	A number of seconds (`float`) or an `httpx.Timeout` object for fine-grained control.
`max_retries`	`2`	How many times to retry failed requests that are safe to retry, such as connection errors, timeouts, 408, 409, 429, and 5xx responses. Set to `0` to disable retries.
`default_headers`	None	A dictionary of headers to send with every request.
`default_query`	None	A dictionary of query parameters to send with every request.
`http_client`	An SDK-managed `httpx` client	A custom HTTP client, for example `DefaultHttpxClient(...)` for proxies. Async clients accept `DefaultAsyncHttpxClient(...)` or `DefaultAioHttpClient()`.

Example with custom timeout and retries:

import httpx
from hiddenlayer import HiddenLayer

client = HiddenLayer(
    # 20 seconds overall, 5 seconds to establish a connection.
    timeout=httpx.Timeout(20.0, connect=5.0),
    max_retries=3,
)

For details on retry behavior and timeout errors, see Error handling.

Use a proxy

If your network requires an HTTP proxy, pass a custom HTTP client. DefaultHttpxClient keeps the SDK’s default settings and adds your changes:

import os

from hiddenlayer import DefaultHttpxClient, HiddenLayer

client = HiddenLayer(
    http_client=DefaultHttpxClient(
        proxy=os.environ["HTTPS_PROXY"],  # For example, http://proxy.example.com:8080
    ),
)

The proxy argument is passed to httpx. Support for it depends on your installed httpx version, because older versions used a proxies argument instead.

Override options for a single request

client.with_options(...) returns a copy of the client with some options changed. The original client is not modified. Use it when one call needs different settings, such as a longer timeout for a large request:

from hiddenlayer import HiddenLayer

client = HiddenLayer()

response = client.with_options(timeout=120.0, max_retries=5).interactions.analyze(
    metadata={"model": "gpt-4o", "requester_id": "user-1234"},
    input={"messages": [{"role": "user", "content": "Summarize this document."}]},
)

Close the client

The client holds open HTTP connections so that it can reuse them. Connections are closed when the client is garbage collected. For predictable cleanup, use the client as a context manager, which closes it when the block ends:

from hiddenlayer import HiddenLayer

with HiddenLayer() as client:
    response = client.interactions.analyze(
        metadata={"model": "gpt-4o", "requester_id": "user-1234"},
        input={"messages": [{"role": "user", "content": "Hello"}]},
    )
    print(response.evaluation)

Alternatively, call client.close() when you are finished. In long-running applications, create one client and reuse it for all requests instead of creating a client per request.

Async client

AsyncHiddenLayer accepts the same arguments and reads the same environment variables as HiddenLayer. Await each method call, and use async with or await client.close() to close it.

import asyncio

from hiddenlayer import AsyncHiddenLayer


async def main() -> None:
    async with AsyncHiddenLayer(environment="prod-us") as client:
        response = await client.interactions.analyze(
            metadata={"model": "gpt-4o", "requester_id": "user-1234"},
            input={"messages": [{"role": "user", "content": "Hello"}]},
        )
        print(response.evaluation)


asyncio.run(main())

To use the aiohttp backend for higher concurrency, install "hiddenlayer-sdk[aiohttp]" and pass DefaultAioHttpClient():

import asyncio

from hiddenlayer import AsyncHiddenLayer, DefaultAioHttpClient


async def main() -> None:
    async with AsyncHiddenLayer(http_client=DefaultAioHttpClient()) as client:
        response = await client.interactions.analyze(
            metadata={"model": "gpt-4o", "requester_id": "user-1234"},
            input={"messages": [{"role": "user", "content": "Hello"}]},
        )
        print(response.evaluation)


asyncio.run(main())

Differences from api.md

The SDK’s generated api.md file has a “Regional Configuration” section that refers to a HIDDEN_LAYER_BASE_URL variable and lists https://api.hiddenlayer.ai as the US host. The SDK source code reads HIDDENLAYER_BASE_URL (no underscore between HIDDEN and LAYER) and uses https://api.us.hiddenlayer.ai for prod-us. Follow the values on this page.

Next step

Quickstart

Make your first authenticated API call.

​Authentication methods

​OAuth2 client credentials

​Bearer token

​Environment variables

​Set environment variables

​Optional: use a .env file

​Choose a region or base URL

​How the client resolves the base URL

​Pass credentials explicitly

​Client options

​Use a proxy

​Override options for a single request

​Close the client

​Async client

​Differences from api.md

​Next step

Quickstart

Authentication methods

OAuth2 client credentials

Bearer token

Environment variables

Set environment variables

Optional: use a .env file

Choose a region or base URL

How the client resolves the base URL

Pass credentials explicitly

Client options

Use a proxy

Override options for a single request

Close the client

Async client

Differences from api.md

Next step