Skip to main content
Before you install the HiddenLayer Python SDK, make sure you have the items on this page. Checking them first saves time, because most setup problems come from a wrong Python version, missing API permissions, or a blocked network connection.

​
Checklist

​
Python

The SDK supports Python 3.9 and later. Python 3.9 reached end of life in October 2025 and no longer receives security fixes, so use Python 3.11 or later for new projects. Check your Python version:
The output should be Python 3.9 or later, for example Python 3.12.4. If your version is older, install a newer Python from python.org or your operating system’s package manager.

​
pip and venv

pip is the Python package installer. venv is the built-in Python module that creates virtual environments. A virtual environment is a self-contained folder with its own Python interpreter and packages, so the SDK’s dependencies do not conflict with other projects on your machine. Check that both are available:
On some Linux distributions, venv is packaged separately from Python. If python3 -m venv --help fails, install your distribution’s venv package (for example, python3-venv on Debian and Ubuntu).

​
HiddenLayer account and API key

You need a HiddenLayer account with access to the HiddenLayer Console. In the Console, create an API key. An API key consists of a client ID and a client secret. The SDK exchanges these for a short-lived access token using OAuth2 client credentials, a standard flow in which an application authenticates as itself rather than as a user. Follow Create API Key to create one. When you create the key:
  • Select the Read, Write, and Delete permissions needed for each product you plan to use. For example, the Interactions SaaS endpoint needs Interactions (Read, Write). See API Permission Related to Products or Features for the full list. Follow the principle of least privilege and grant only what your code needs. If the key lacks a permission, the SDK raises PermissionDeniedError (HTTP 403) for that product’s endpoints.
  • Copy the client secret and store it securely. Treat it like a password.
Never paste your client secret into source code, notebooks, or commits. The SDK reads credentials from environment variables. See Authentication and configuration.

​
Region or base URL

HiddenLayer runs separate regional environments. Your API key works only in the region where it was created, because the SDK requests tokens from the same host it sends API calls to. If you use a self-hosted deployment or a locally running AI Runtime Security container, you need its base URL instead, for example http://localhost:8000. Ask your administrator if you are not sure which applies to you.

​
Network access

The machine that runs your code must be able to reach the API host for your region over HTTPS (port 443). If your organization routes traffic through a proxy or firewall, confirm that the host is allowed. You can configure a proxy in the SDK. See Authentication and configuration. Some workflows also need network access to other services:
  • Hugging Face model scans download files from Hugging Face.
  • S3 and Azure Blob Storage model scans download files from your cloud storage.
  • Red team sessions send attack prompts to your target AI application, which your code calls.

​
Optional packages by workflow

The core SDK installs everything needed for most API calls. A few helpers rely on third-party packages that you install separately, only if you use that helper. Installation commands for these packages are on the Installation page.

​
Next step

Install the SDK

Create a virtual environment and install hiddenlayer-sdk.