Authentication

All requests to the Ionworks API require an API key. This page covers how to obtain a key and configure the client.

Obtaining an API key

You can generate an API key from the Ionworks account settings page. Keep the key safe — it will only be shown once.

Configuration

The client reads credentials from environment variables by default. The repository includes a .env.example file you can copy as a starting point:

cp .env.example .env

Then fill in your values:

.env.example

# Ionworks API credentials
# Get your API key from https://app.ionworks.com/dashboard/account
IONWORKS_API_KEY=your_api_key_here

# API URL (optional, defaults to https://api.ionworks.com)
IONWORKS_API_URL=https://api.ionworks.com

# DataFrame backend for returned data (optional, defaults to "polars")
# Options: "polars" or "pandas"
IONWORKS_DATAFRAME_BACKEND=polars

# Project ID for pipeline operations
# Found in your project settings page at https://app.ionworks.com
PROJECT_ID=your_project_id_here

Set the required IONWORKS_API_KEY variable, and uncomment any optional variables you need. If you work with pipelines, you will also need to set PROJECT_ID — you can find it on your project settings page.

The client loads your .env file automatically via python-dotenv. Alternatively, export the variables in your shell:

export IONWORKS_API_KEY="your-api-key"

Initializing the client

from ionworks import Ionworks

# Reads IONWORKS_API_KEY and IONWORKS_API_URL from the environment
client = Ionworks()

You can also pass credentials directly — this takes precedence over environment variables:

client = Ionworks(api_key="your-api-key", api_url="https://api.ionworks.com")

Request configuration

The client supports configuring request timeout and retry behavior:

# Default: 10 second timeout, 5 retries
client = Ionworks()

# Custom timeout (in seconds)
client = Ionworks(timeout=30)

# Custom maximum retries
client = Ionworks(max_retries=3)

# Both custom
client = Ionworks(timeout=20, max_retries=10)

• timeout: Request timeout in seconds. Defaults to 10 seconds.

• max_retries: Maximum number of retries for failed requests. Defaults to 5. Retries occur automatically on connection errors, timeouts, and 5xx server errors with exponential backoff.

Verifying connectivity

Call health_check() to confirm the client can reach the API:

health = client.health_check()
print(health)

Troubleshooting

Symptom	Cause	Fix
ValueError on init	IONWORKS_API_KEY is not set and no key was passed	Set the environment variable or pass api_key=
IonworksError with status 401	Invalid or expired API key	Regenerate the key in account settings
Connection timeout	Network or firewall issue, or default timeout too short	Check that https://api.ionworks.com is reachable, or increase timeout: Ionworks(timeout=30)
Requests timing out frequently	Default 10s timeout may be too short for slow operations	Increase timeout: Ionworks(timeout=60)

Next steps

With the client authenticated you can start managing cells — see Cell Specifications.