Bring Your Own Key (BYOK)

Take control of your AI analytics costs by using your own Claude or OpenAI API keys with Scoop.

What is BYOK?

Bring Your Own Key (BYOK) is an enterprise feature that allows you to use your own AI provider API keys instead of consuming Scoop's AI credits. When you configure BYOK, all AI-powered analytics in your account will use your API key directly with Claude or OpenAI.

Why Use BYOK?

Cost Control

Direct billing relationship with AI provider
Use your existing enterprise agreements
Pay only for what you use
No consumption of Scoop AI credits

Enterprise Requirements

Meet corporate procurement policies
Use approved vendor accounts
Maintain audit trails through your provider
Consolidated billing across tools

Flexibility

Choose between Claude (Anthropic) or OpenAI
Switch providers anytime
Revert to Scoop's system AI with one click
Test keys before activating

How BYOK Works

Without BYOK:
User → Scoop → Scoop's AI Provider → AI Response
                (uses Scoop credits)

With BYOK:
User → Scoop → Your AI Provider Account → AI Response
                (uses your API key)

Your data never leaves Scoop's secure infrastructure. Only API requests are routed through your API key.

Getting Started with BYOK

Prerequisites

Account Role: Account Owner or Admin
API Key: Valid Claude or OpenAI API key
Billing: Active billing account with your chosen AI provider

Step 1: Get Your API Key

For Claude (Anthropic)

Visit console.anthropic.com
Sign in or create an account
Navigate to API Keys section
Click Create Key
Name your key (e.g., "Scoop Analytics")
Copy the key (starts with sk-ant-)
Important: Save this key securely - you won't see it again

Recommended Setup:

Enable usage limits to control costs
Set up billing alerts
Use workspace-level keys for better tracking

For OpenAI

Visit platform.openai.com
Sign in or create an account
Navigate to API Keys section
Click Create new secret key
Name your key (e.g., "Scoop Analytics")
Copy the key (starts with sk-)
Important: Save this key securely - you won't see it again

Recommended Setup:

Set usage limits in your OpenAI account
Enable billing alerts
Consider using project-specific keys

Step 2: Configure BYOK in Scoop

Web Application

Click your profile icon in the top-right corner
Select Account Settings
Navigate to the AI Provider tab
You'll see three options:
- System Default (uses Scoop's AI)
- Claude (Anthropic)
- OpenAI
Select your provider from the dropdown
Enter your API key:
- Paste the API key you copied earlier
- The key will be masked for security
- A hint shows where to get keys if needed
Test your key (recommended):
- Click "Test API Key" button
- Wait for validation (5-10 seconds)
- Success: "API key is valid and working"
- Failure: Check your key and try again
Save your settings:
- Click "Save Settings"
- Confirmation: "BYOK is now active"
- Your account now uses your API key

What happens after saving:

All AI queries use your API key
Active BYOK banner appears at top of settings
API key field shows "Currently configured" badge
Original key field clears (security feature)

Step 3: Verify BYOK is Active

After saving, you'll see:

Visual Indicators:

Green banner: "BYOK is active - Using [Provider]"
Status badge on API key field
Provider dropdown shows your selection

Test with a Query:

Navigate to any dataset in Scoop
Ask a question: "Show me a summary of this data"
Watch your AI provider dashboard for usage
Verify the request appears in your provider's logs

Managing Your BYOK Settings

Viewing Current Settings

Navigate to Account Settings → AI Provider anytime to see:

Current provider (System/Claude/OpenAI)
Whether a custom key is configured
BYOK active status

Note: For security, you cannot view the actual API key after saving. You can only see whether one is configured.

Changing Your API Key

To update your API key:

Go to Account Settings → AI Provider
Select the same or different provider
Enter the new API key
Click "Test API Key" (recommended)
Click "Save Settings"

The old key is immediately replaced with the new one.

Switching Providers

To switch from Claude to OpenAI (or vice versa):

Go to Account Settings → AI Provider
Select the new provider from dropdown
Enter the new provider's API key
Test and save

All future queries will use the new provider.

Reverting to System Default

To stop using BYOK and return to Scoop's AI:

Go to Account Settings → AI Provider
Click "Clear & Use System Default" button
Confirm the action
Success message: "Settings cleared. Using system defaults."

What happens:

Your API key is removed from Scoop
Account returns to using Scoop's AI credits
No data is lost
You can re-enable BYOK anytime

Understanding BYOK Behavior

What Uses Your API Key

When BYOK is active, these features use your key:

All natural language queries
"Why" questions and investigations
Machine learning analysis
Predictive analytics
Dataset summaries and insights
Chart and visualization generation
Canvas and presentation creation

What Doesn't Change

BYOK only affects AI provider routing. These remain the same:

Your datasets and data storage
Scoop's analysis algorithms
Visualization capabilities
Data security and privacy
User permissions and access control

Cost Implications

With BYOK Enabled:

You pay your AI provider directly
Costs depend on usage (tokens processed)
No Scoop AI credits consumed
Monitor costs in your provider's dashboard

Typical Usage Patterns:

Query Type	Approximate Token Usage	Estimated Cost*
Simple query	1,000-5,000 tokens	$0.01-$0.05
Complex investigation	10,000-50,000 tokens	$0.10-$0.50
ML analysis	20,000-100,000 tokens	$0.20-$1.00
Canvas generation	30,000-150,000 tokens	$0.30-$1.50

*Estimates based on Claude/OpenAI pricing as of 2025. Actual costs vary by model and provider.

Performance Considerations

Response Times:

BYOK queries may be slightly faster or slower depending on your provider's API performance
Typical difference: negligible (less than 500ms)
Provider rate limits apply to your account

Rate Limits:

Governed by your API key's tier/plan
If you hit rate limits, queries will fail with clear error messages
Upgrade your provider plan or switch back to System Default if needed

Troubleshooting

"API key test failed"

Possible Causes:

Invalid API key - Key copied incorrectly or expired
- Solution: Double-check the key, ensure no extra spaces
- Generate a new key from your provider
Insufficient permissions - Key doesn't have required permissions
- Solution: Ensure key has full API access, not read-only
Account issue with provider - Billing problem or suspended account
- Solution: Check your provider dashboard for account status
Rate limit exceeded - Too many test attempts
- Solution: Wait a few minutes and try again

"Settings saved but BYOK not active"

This happens when you save a partial configuration (provider without key, or key without provider).

Solution:

Select a provider from dropdown
Enter the corresponding API key
Save again
Both provider AND key must be set for BYOK to activate

"BYOK queries failing in Scoop"

Symptoms: Queries return errors after enabling BYOK

Troubleshooting Steps:

Verify key is still valid:
- Go to Account Settings → AI Provider
- Click "Test API Key"
- If test fails, key may have been revoked
Check provider account status:
- Visit your Claude or OpenAI dashboard
- Verify billing is current
- Check for service alerts
Check rate limits:
- High usage may have hit provider rate limits
- Review usage in provider dashboard
- Consider upgrading plan or temporarily reverting to System Default
Re-save settings:
- Sometimes helps after provider-side issues
- Go to Account Settings → AI Provider
- Test key, then save again
Revert temporarily:
- Click "Clear & Use System Default"
- Verify queries work with system AI
- Re-enable BYOK once issue is resolved

"Only visible to owners and admins"

Cause: You don't have sufficient permissions

Solution:

Contact your account owner or admin
Request they configure BYOK or upgrade your role
BYOK is account-level and affects all users

API Key Security Concerns

"I accidentally committed my API key to code":

Immediately revoke the key in your provider dashboard
Generate a new key
Update BYOK settings with new key
Review provider logs for unauthorized usage

"Can Scoop see my API key?":

Keys are encrypted at rest in Scoop's database
Keys are never logged or exposed in UI after saving
Keys are transmitted over HTTPS only
Scoop staff cannot view your raw keys

Security & Best Practices

API Key Security

Do's:

✅ Generate separate keys for Scoop (don't share with other apps)
✅ Set usage limits in your provider dashboard
✅ Enable billing alerts to monitor unexpected usage
✅ Rotate keys periodically (every 90 days recommended)
✅ Revoke keys immediately if compromised

Don'ts:

❌ Share API keys with other users or applications
❌ Store keys in plain text outside of Scoop
❌ Use personal API keys for organizational accounts
❌ Ignore unusual usage patterns in provider dashboard

Cost Management

Monitor Usage:

Check your provider dashboard weekly
Set up billing alerts at reasonable thresholds
Review which users/queries consume most tokens
Compare costs: BYOK vs Scoop credits

Control Costs:

Set hard usage limits in provider dashboard
Start with lower limits and increase as needed
Consider reverting to System Default during high-usage periods
Use provider's budgeting tools

Compliance & Governance

For Enterprise Teams:

Document BYOK configuration in internal wiki
Assign BYOK management to specific admin(s)
Include API keys in security key rotation policies
Add provider accounts to vendor management system
Ensure BYOK usage complies with data governance policies

Frequently Asked Questions

General Questions

Q: Does BYOK cost extra in Scoop? A: No, BYOK is included in your Scoop subscription. You only pay for AI usage through your provider.

Q: Can I use BYOK with Scoop for Slack? A: Yes! BYOK is account-level. Once configured, it applies to web app, Slack, and all Scoop interfaces.

Q: Can different users in my account use different API keys? A: No, BYOK is account-level. All users in the account share the same AI provider configuration.

Q: What happens if my API key expires? A: Queries will fail with error messages. Update your key in Account Settings to restore functionality.

Q: Can I use both Claude and OpenAI simultaneously? A: No, you can only use one provider at a time. You can switch providers anytime, but only one is active.

Provider-Specific Questions

Q: Which Claude model does Scoop use with BYOK? A: Scoop automatically selects the optimal Claude model for each task (typically Claude 3.5 Sonnet or Claude 3 Opus).

Q: Which OpenAI model does Scoop use with BYOK? A: Scoop uses GPT-4 and GPT-4 Turbo for most queries, selecting based on task complexity and latency requirements.

Q: Can I specify which model to use? A: No, Scoop automatically selects models. This ensures optimal performance and accuracy.

Q: Does BYOK work with Azure OpenAI? A: Not currently. BYOK supports standard OpenAI API keys only. Azure OpenAI support may be added in the future.

Technical Questions

Q: Where is my API key stored? A: Keys are encrypted and stored in Scoop's secure database, accessible only to your account.

Q: Can I see my API key after saving? A: No, for security reasons keys are not retrievable. You can only see if one is configured.

Q: Does BYOK affect data privacy? A: No, your data handling remains the same. Only the AI provider routing changes.

Q: What if my provider has an outage? A: Queries will fail. You can temporarily revert to System Default to continue working.

Q: Can I set different BYOK for production vs development? A: No, BYOK is account-level. Consider using separate Scoop accounts for dev/prod if needed.

Getting Help

Support Resources

Documentation:

Understanding Scoop AI - How Scoop's AI works
Machine Learning Analytics - AI-powered features

Provider Support:

Claude: Anthropic Documentation
OpenAI: OpenAI Documentation

Scoop Support:

Email: [email protected]
Include "BYOK" in subject line for faster routing
Provide account ID and provider (don't include actual API key)

Reporting Issues

If BYOK isn't working as expected:

Test your API key in Account Settings
Check provider status at your provider's dashboard
Collect information:
- Error messages from Scoop
- Browser console errors (if applicable)
- Approximate time of issue
- Provider and account ID
Contact Scoop support with details above

Never share your actual API key with support. We can diagnose issues without seeing your key.

Summary

BYOK gives you control over AI costs and vendor relationships while maintaining Scoop's powerful analytics capabilities.

Key Takeaways:

Configure BYOK in Account Settings → AI Provider
Test keys before saving
Monitor usage in your provider dashboard
Revert to System Default anytime
Contact support if you need help

Ready to get started? Get your API key and configure BYOK in minutes.

Last Updated: January 2025 Feature Status: Generally Available Supported Providers: Claude (Anthropic), OpenAI