API Keys

API keys are the primary way to authenticate programmatically with BiOS. Each key is scoped to a single workspace within an organization, so no additional org/workspace headers are needed. API keys are used by the TypeScript SDK, Python SDK, MCP Server, and direct API calls.

Creating an API Key

Follow these steps to create your first API key:

1. Sign in to the console at https://bios.us.com.
2. Open Settings. Click Settings in the left sidebar of your dashboard.
3. Go to API Keys. Select the API Keys tab within Settings.
4. Click “Create API Key”. Enter a descriptive name (e.g. “CI/CD Pipeline”, “Python Development”, “MCP Server”).
5. Select scopes. Choose the permission scopes your key needs (see table below).
6. Copy the key immediately. The key (starts with sk_live_) is shown only once. Store it in a secure location.

Using Your API Key

Set the key as an environment variable so your SDKs and scripts pick it up automatically:

# Set in your shell profile (~/.bashrc, ~/.zshrc)
export USFBIOS_API_KEY=sk_live_your_key_here

# Or pass inline for a single command
USFBIOS_API_KEY=sk_live_... python train.py

TypeScript SDK

import { USFBios } from '@usfbios/sdk';

// Reads USFBIOS_API_KEY from environment automatically
const client = new USFBios();

// Or pass explicitly
const client = new USFBios({ apiKey: 'sk_live_...' });

// List models
const models = await client.models.list();

Python SDK

from usfbios import USFBios

# Reads USFBIOS_API_KEY from environment automatically
client = USFBios()

# Or pass explicitly
client = USFBios(api_key="sk_live_...")

# List models
models = client.models.list()

cURL

curl https://api.usbios.ai/api/models \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json"

Required Headers

Primary: API Key (recommended for SDK, MCP, and scripts):

X-API-Key: sk_live_your_key_here
Content-Type: application/json

Alternative: JWT Bearer Token (used by the web console):

Authorization: Bearer <access_token>
X-Org-ID: <organization_id>
X-Workspace-ID: <workspace_id>
Content-Type: application/json

JWT tokens are obtained via POST /api/auth/login and expire periodically. API keys are the recommended method for programmatic access and may have an explicit expiration.

Key Introspection

Verify what your key can do by calling the introspection endpoint:

curl https://api.usbios.ai/api/api-keys/introspect \
  -H "X-API-Key: sk_live_your_key_here"

Response:

{
  "auth_type": "api_key",
  "key_id": "ak_abc123",
  "key_name": "CI/CD Pipeline",
  "key_prefix": "sk-usf-PREFIX",
  "status": "active",
  "scopes": ["datasets:read", "datasets:write", "training:read", "training:write"],
  "scope_preset": "custom",
  "org": { "id": "org_7f3e9a2d1c84b056", "name": "" },
  "workspace": { "id": "ws_a1b2c3d4", "name": "" },
  "user": { "id": "usr_123", "name": "Jane", "email": "jane@example.com", "role": "" },
  "scope_details": [{ "scope": "training:write", "description": "Create, stop, resume, dequeue, and delete checkpoints for training jobs.", "tools": ["create_training_job"], "sdk_methods": ["training.create"] }],
  "allowed_mcp_tools": ["introspect_api_key", "list_datasets", "create_training_job"],
  "allowed_sdk_methods": ["introspect", "datasets.list", "training.create"],
  "expires_at": "2026-08-01T10:00:00Z",
  "created_at": "2026-07-01T10:00:00Z"
}

Managing & Rotating Keys

Best practices for API key management:

• Use descriptive names. Name each key by its purpose (e.g. “Production Training”, “CI Pipeline”, “Local Development”).
• Principle of least privilege. Only grant the scopes each key actually needs. A key that only reads models does not need training:write.
• Rotate regularly. Delete old keys and create new ones periodically. To rotate: create a new key, update your environment, verify it works, then delete the old key.
• Never commit keys. Use environment variables or a secrets manager. Never put keys in source code, config files, or documentation.
• One key per integration. Use separate keys for your CI pipeline, local dev, and production. If one is compromised, revoke it without affecting the others.

Permission Scopes

Each API key is created with a set of permission scopes that control what operations it can perform:

Common Key Patterns

Recommended scope combinations for common use cases: