Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

Bring Your Own Keys (BYOK) mode lets you use your own AI provider API keys with Rigbox workspaces. Your keys are stored securely and injected into the workspace runtime - you get unlimited usage billed directly by your provider, with no Rigbox credit limits.
Managed mode routes traffic through Rigbox’s OpenRouter gateway and meters it against your credit balance. BYOK skips OpenRouter entirely and connects your workspace directly to the provider you specify, using the key you supply.

​
When to Use BYOK

BYOK is the right choice when:
  • You already have API keys from Anthropic, OpenAI, Google, or another provider
  • You need unlimited usage beyond the managed credit tiers
  • You need a specific model not available in managed mode
  • Your organization requires that API keys stay under your own provider account for billing, audit, or compliance reasons
If you are just getting started or prototyping, managed mode is faster to set up - no keys needed.

​
Set BYOK Mode

Configure a workspace to use your own API key by setting the AI config to byok mode. 
curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider": "openai",
    "api_key": "sk-proj-...",
    "model": "gpt-4o"
  }'
The API never returns your API key in responses. Once set, you can update or clear the key, but you cannot read it back. Treat it as a write-only field.

​
How Keys Are Stored and Injected

When you set a BYOK key:
  1. Encrypted at rest - the key is encrypted before being written to the database
  2. Injected at runtime - when the workspace starts, the key is injected as an environment variable inside the VM
  3. Never logged - keys are redacted from all request logs and audit trails
  4. Scoped to the workspace - each workspace has its own AI config; changing one does not affect others
The key is available inside the workspace as the standard environment variable for the provider SDK (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY).

​
Clear a Key

To remove an API key from a workspace without changing the mode: 
curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider": "openai",
    "api_key": null
  }'
Setting api_key to null removes the stored key. The workspace will no longer have access to the provider until you set a new key.

​
Switch Back to Managed Mode

You can switch from BYOK to managed mode at any time. This clears the stored key and starts using Rigbox-managed credits instead. 
curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "managed",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }'
Switching modes takes effect on the next AI API call - no workspace restart required.

​
Set Defaults for New Workspaces

If you use the same provider and key across most of your workspaces, set a default so new workspaces inherit your BYOK configuration automatically. 
curl -X PUT https://api.rigbox.dev/api/v1/users/me/ai-defaults \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider": "anthropic",
    "api_key": "sk-ant-...",
    "model": "claude-sonnet-4-20250514"
  }'
New workspaces will use these defaults unless you explicitly override the AI config at creation time. See the AI Defaults API reference for the full schema.

​
Managed vs. BYOK Comparison

FeatureManagedBYOK
API keys requiredNoYes
Credit trackingAutomaticN/A (billed by your provider)
CostIncluded credits (Free: 250, Pro: 2,000)Your provider billing
Supported providersAnthropic, OpenAI, Google, BraveAny supported provider
Usage limitsCredit balanceYour provider’s rate limits
Setup timeInstantNeed existing API key
Best forQuick start, prototyping, demosProduction, high volume, specific models

​
Provider-Specific Examples

​
Anthropic (Claude)

curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider": "anthropic",
    "api_key": "sk-ant-api03-...",
    "model": "claude-sonnet-4-20250514"
  }'
Inside the workspace: 
from anthropic import Anthropic

# ANTHROPIC_API_KEY is injected automatically
client = Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude!"}]
)
print(message.content[0].text)

​
OpenAI (GPT)

curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider": "openai",
    "api_key": "sk-proj-...",
    "model": "gpt-4o"
  }'
Inside the workspace: 
from openai import OpenAI

# OPENAI_API_KEY is injected automatically
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello, GPT!"}]
)
print(response.choices[0].message.content)

​
Google (Gemini)

curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider": "google",
    "api_key": "AIza...",
    "model": "google/gemini-2.5-pro"
  }'
Inside the workspace: 
import google.generativeai as genai

# GOOGLE_API_KEY is injected automatically
model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content("Hello, Gemini!")
print(response.text)

​
Security Best Practices

Never set API keys using raw environment variables or .env files inside the workspace. Always use the ai-config endpoint - it ensures keys are encrypted, scoped, and never exposed in logs.
  • Rotate keys regularly - update the key via the ai-config endpoint; no workspace restart needed
  • Use scoped keys - if your provider supports project-scoped or restricted keys, prefer those over organization-wide keys
  • Audit usage - monitor your provider dashboard for unexpected usage patterns
  • One key per workspace - avoid sharing the same key across many workspaces; this makes it easier to revoke access to a single workspace

​
Next Steps