---
title: Authentication | Boltz API Docs
description: Choose between API keys, OAuth bearer tokens, and share-link access.
---

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](/docs/api/guides/share-links/index.md) 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](#tab-panel-0-0)
- [CLI](#tab-panel-0-1)
- [TypeScript](#tab-panel-0-2)

```
import os
from boltz_api import Boltz


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

Terminal window

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

```
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:

Terminal window

```
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:

Terminal window

```
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:

Terminal window

```
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](/docs/api/guides/organizations-and-workspaces/index.md) for more on how workspaces and keys relate.