What Is BYOK
BYOK (Bring Your Own Key) lets you configure your own LLM provider credentials and use them for conversion instead of the key 3XCode provides by default. Once set up, thepyspark convertand pyspark analyzecommands route to your provider account automatically, no per-command flag needed.
Stored Locally Only
Keys are saved via your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) with a local JSON fallback protected by owner-only file permissions. The raw key is never sent to the 3XDE backend.
Metadata-Only Registration
Only the provider name and your preferred model list are registered with the backend so licensing and usage tracking still work. The secret itself stays on your machine.
Four Supported Providers
Anthropic (direct API), AWS Bedrock, Google Vertex AI, and Azure AI Foundry. Pick whichever your organization already has billing set up with.
Your Code Never Touches Our Servers
This is true whether you use BYOK or the platform key: source SQL is sent directly to your chosen LLM provider, never to the 3XDE backend. The backend only handles auth, licensing, and usage metadata.
Before You Start
Two things need to be true before keys store will let you proceed: you need to be logged in, and BYOK needs to be enabled for your account. BYOK is admin-gated: if your account isn't yet assigned byok as its key source, ask your admin to enable it.
# 1. Log in (opens a browser for the device flow by default) 3xcode login # 2. If BYOK isn't enabled yet for your account, request it 3xcode contact-admin -m "Please enable BYOK for my account"
If BYOK isn't yet approved, keys store will still let you save a key locally (the check is best-effort and optimistic offline), but actual conversions will keep using the platform key until an admin flips your account's key source to byok.
Set Up Anthropic Direct
Anthropic direct is the default provider and the simplest to configure: just one secret field. Walking through it end to end:
Run keys store
Start the interactive setup for the anthropic provider.
Paste your API key
ANTHROPIC_API_KEY is the only required field, entered hidden.
Pick preferred models
Choose opus, sonnet, haiku, or Enter for all.
Convert as usual
pyspark convert automatically routes to your key.
Step 1: Start the store flow
Run keys store with--provider anthropic, or omit the flag and pick from the interactive menu:
3xcode keys store --provider anthropic
Step 2: Provide your credential
You'll be prompted for a single secret field, entered hidden (via getpass, not echoed to the terminal):
| Field | Type | Example |
|---|---|---|
ANTHROPIC_API_KEY | Secret | sk-ant-... |
Step 3: Choose preferred models
Next you'll be asked which models you want available through this key:opus,sonnet (Claude Sonnet 5, the default), orhaiku. Enter comma-separated numbers, or just press Enter to allow all three. This list (not the key itself) is what gets registered with the backend.
Step 4: Where it's stored
The key is written to ~/.3xcode/providers/anthropic.json, owner-only permissions. If your OS keychain is available,ANTHROPIC_API_KEY is stored there instead and the JSON file just holds a placeholder. Either way, only the provider name and your preferred models are sent to the 3XDE backend via register_byok; the key itself never leaves your machine. From this point on, every 3xcode pyspark convert and 3xcode pyspark analyze call uses it automatically.
Other Providers
AWS Bedrock, Google Vertex AI, and Azure AI Foundry all follow the exact same3xcode keys store --provider <name> pattern shown above, only the fields you're prompted for differ. Swap the provider name and answer the provider-specific prompts:
3xcode keys store --provider bedrock 3xcode keys store --provider vertex 3xcode keys store --provider azure
| Provider | Prompted Fields | What It Sets |
|---|---|---|
| AWS Bedrock | AWS_ACCESS_KEY_ID (secret), AWS_SECRET_ACCESS_KEY (secret), AWS_REGION | CLAUDE_CODE_USE_BEDROCK=1 |
| Google Vertex AI | CLOUD_ML_REGION, ANTHROPIC_VERTEX_PROJECT_ID | CLAUDE_CODE_USE_VERTEX=1 |
| Azure AI Foundry | ANTHROPIC_FOUNDRY_API_KEY (secret), ANTHROPIC_FOUNDRY_BASE_URL | CLAUDE_CODE_USE_FOUNDRY=1 |
AWS Bedrock
No AWS profile or SSO support currently: only a raw access key / secret key pair, plus the AWS region string (e.g. us-east-1).
Google Vertex AI
The interactive prompt collects your Vertex region and project ID.
Azure AI Foundry
Needs your Foundry API key plus the Azure endpoint URL for your deployment (ANTHROPIC_FOUNDRY_BASE_URL).
One Provider Active at a Time
All conflicting provider env flags are cleared before exactly one is set per your configured provider, so there's no ambiguity about which account a conversion bills against.
Verify & Manage Your Keys
Once a key is stored, use these commands to confirm it works and to manage it over time:
keys list
Table of every stored provider, masked credential values, preferred models, and whether it's backed by your OS keyring or the local file fallback.
keys test
Makes a minimal live API call to confirm the key actually works, and reports latency, the model tested, and BYOK approval state. Only available when your account is in BYOK mode.
keys status
Quick summary of which key source is active: your local BYOK provider, or the platform-provided key if none is configured.
keys delete
Removes a provider's credentials from both the OS keyring and the local JSON file. Whether conversions still work afterward depends on your account's backend key-source setting; see keys status.
# See everything you've stored 3xcode keys list # Confirm the anthropic key actually works 3xcode keys test --provider anthropic # Check which source (BYOK vs platform) is currently active 3xcode keys status # Remove a key you no longer need 3xcode keys delete anthropic