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

# Default project ID for project-scoped operations (pipelines, studies,
# optimizations, cell specs, ...). Used as the default when sub-client
# methods don't pass project_id explicitly.
# Find it in the URL of your project settings page:
# https://app.ionworks.com/dashboard/projects/<project-id>/settings
IONWORKS_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 or any other project-scoped resource, set IONWORKS_PROJECT_ID — you can copy it from the project settings page at https://app.ionworks.com/dashboard/projects/<your-project-id>/settings. (PROJECT_ID is still accepted for backwards compatibility but is deprecated and will be removed in a future release.)

The client reads its configuration from environment variables but does not load .env files itself. Load your .env explicitly with python-dotenv before constructing the client:

from dotenv import load_dotenv
load_dotenv()

from ionworks import Ionworks
client = Ionworks()

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, IONWORKS_API_URL, and IONWORKS_PROJECT_ID
# 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",
    project_id="your-project-id",
)

Default project ID#

When IONWORKS_PROJECT_ID is set (or project_id= is passed to the client), every sub-client method that takes a project_id argument uses that value as the default. You can still pass an explicit project_id to override it on a per-call basis:

# Uses IONWORKS_PROJECT_ID
client.study.create({"name": "Discharge study"})

# Override for a single call
client.study.create({"name": "Discharge study"}, project_id="other-project")

This means scripts no longer need to thread a project_id through every call site or stamp it into every payload.

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 revoked API key (keys do not expire, but regenerating one invalidates the previous 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.