Authentication

Boltz supports three customer-facing authentication patterns:

Credential	Best for	Where it works
API key in x-api-key	Services, CI, SDKs, and other non-interactive workloads	Authenticated API routes, subject to the key’s type and permissions
OAuth access token in Authorization: Bearer	Interactive CLI and signed-in user sessions	Compute routes, share-link management, and auth inspection
Share-link ID in the URL	Giving someone read-only access to selected results	Public share-link read routes only; email-restricted links also require an OAuth access token

API keys and OAuth access tokens are credentials for authenticated API operations. A share-link ID is a narrower bearer credential that grants only the read access encoded by that link. See Share links for the share-link access modes.

Authenticate with an API key

Read BOLTZ_API_KEY from your environment and pass it to your SDK client:

Python

import os
from boltz_api import Boltz

client = Boltz(
    base_url="https://api.boltz.bio",
    api_key=os.environ["BOLTZ_API_KEY"])

CLI

export BOLTZ_BASE_URL="https://api.boltz.bio"
export BOLTZ_API_KEY="your-api-key"
boltz-api auth status

TypeScript

import Boltz from "boltz-api";

const apiKey = process.env["BOLTZ_API_KEY"];

const client = new Boltz({
  baseURL: "https://api.boltz.bio",
  apiKey });

Use an API key with any HTTP client

Pass the key in the x-api-key request header:

x-api-key: <your-api-key>

The SDKs and CLI set this header from BOLTZ_API_KEY (or the api_key passed to an SDK client). You can also send it from curl, another HTTP client, or an egress proxy that injects the key so it never lives in the calling environment:

curl https://api.boltz.bio/compute/v1/auth/me \
  -H "x-api-key: $BOLTZ_API_KEY"

Requests are not signed.

Choose the right key type

There are two types of API keys. Which one you use depends on what you need to do.

Admin keys

Use an admin key. Admin keys are scoped to the organization level and can:

• Create, list, and update workspaces
• Manage API keys for any workspace
• Run jobs across the organization
• Query usage data across the organization
• Create and manage share links for resources they can read

For job endpoints that accept workspace_id, an admin key can target any non-archived workspace in the organization. If workspace_id is omitted, the request uses the default workspace.

Workspace keys

Use a workspace key when an integration should be confined to one workspace. Workspace keys can run jobs in that workspace, create and manage share links for resources they can read, and retrieve their own workspace metadata and spending limit. They cannot create workspaces, change spending limits, manage API keys, or query organization-wide usage. If workspace_id is provided, it must match the key’s assigned workspace.

Key scoping summary

Capability	Admin key	Workspace key
Manage workspaces and spending limits	Yes	No
Read a workspace spending limit	Any workspace in the organization	Assigned workspace only
Manage API keys	Yes	No
Run jobs	Any workspace in the organization; defaults to the default workspace when workspace_id is omitted	Assigned workspace only
Manage share links	For readable resources in any organization workspace	For readable resources in the assigned workspace
Query organization usage	Yes	No

Key prefixes

Each key type has a distinct prefix so you can identify it at a glance:

Prefix	Key type
sk_bc_admin_live_	Admin key (live)
sk_bc_admin_test_	Admin key (test)
sk_bc_ws_live_	Workspace key (live)
sk_bc_ws_test_	Workspace key (test)

The full key is shown only once, at creation time. After that, use the key_prefix field on the API key resource to identify which key you’re looking at.

Use the Test environment to validate your integration without incurring cost. Test mode returns synthetic results. No real model inference runs, no GPU usage, and no billing. The metrics and structures returned are placeholders.

Authenticate with OAuth

OAuth is intended for interactive user sessions. The Boltz CLI handles login, secure token storage, refresh, and logout:

export BOLTZ_BASE_URL="https://api.boltz.bio"
boltz-api --auth-issuer-url "https://lab.boltz.bio" auth login
boltz-api auth status

For coding agents or remote shells where a localhost callback is impractical, use device authorization:

export BOLTZ_BASE_URL="https://api.boltz.bio"
boltz-api --auth-issuer-url "https://lab.boltz.bio" auth login --device-code
boltz-api auth status

The CLI uses an OAuth bearer token when no API key is configured. If both BOLTZ_API_KEY and a stored OAuth session are available, the API key takes precedence.

When calling the REST API with an access token obtained through a supported Boltz OAuth flow, send it as:

Authorization: Bearer <access-token>

OAuth bearer tokens are supported by compute operations, share-link management, and GET /compute/v1/auth/me. Organization management routes under /compute/v1/admin require an admin API key.

An OAuth user can belong to more than one organization. Call GET /compute/v1/auth/me to inspect the available memberships, then select an organization with:

X-Boltz-Organization-Id: <organization-id>

For requests containing a workspace_id, the API can infer the organization from a workspace in one of the user’s memberships. Otherwise, callers with multiple memberships should send X-Boltz-Organization-Id.

The generated Python and TypeScript SDK clients expose API-key configuration. Use the CLI for managed OAuth login, or send the bearer token with a direct HTTP client.

Share-link authentication

Share links use the link ID in /compute/v1/share/{id} as a scoped bearer credential:

• Public links require no API key or OAuth token. Anyone with the URL can read the selected resources until the link expires or is archived.
• Email-restricted links require the link ID plus a Boltz OAuth access token whose verified email is on the link’s allowlist.

Do not put share-link URLs in logs, analytics payloads, or public pages. Treat them as secrets even when email access is also required.

See Organizations & Workspaces for more on how workspaces and keys relate.