# Bring Your Own Key (BYOK)

# 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)

1. Visit [console.anthropic.com](https://console.anthropic.com)
2. Sign in or create an account
3. Navigate to **API Keys** section
4. Click **Create Key**
5. Name your key (e.g., "Scoop Analytics")
6. Copy the key (starts with `sk-ant-`)
7. **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

1. Visit [platform.openai.com](https://platform.openai.com)
2. Sign in or create an account
3. Navigate to **API Keys** section
4. Click **Create new secret key**
5. Name your key (e.g., "Scoop Analytics")
6. Copy the key (starts with `sk-`)
7. **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

1. Click your **profile icon** in the top-right corner

2. Select **Account Settings**

3. Navigate to the **AI Provider** tab

4. You'll see three options:
   * **System Default** (uses Scoop's AI)
   * **Claude** (Anthropic)
   * **OpenAI**

5. **Select your provider** from the dropdown

6. **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

7. **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

8. **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**:

1. Navigate to any dataset in Scoop
2. Ask a question: "Show me a summary of this data"
3. Watch your AI provider dashboard for usage
4. 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:

1. Go to **Account Settings → AI Provider**
2. Select the same or different provider
3. Enter the new API key
4. Click **"Test API Key"** (recommended)
5. Click **"Save Settings"**

The old key is immediately replaced with the new one.

### Switching Providers

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

1. Go to **Account Settings → AI Provider**
2. Select the new provider from dropdown
3. Enter the new provider's API key
4. 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:

1. Go to **Account Settings → AI Provider**
2. Click **"Clear & Use System Default"** button
3. Confirm the action
4. 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**:

1. **Invalid API key** - Key copied incorrectly or expired
   * Solution: Double-check the key, ensure no extra spaces
   * Generate a new key from your provider

2. **Insufficient permissions** - Key doesn't have required permissions
   * Solution: Ensure key has full API access, not read-only

3. **Account issue with provider** - Billing problem or suspended account
   * Solution: Check your provider dashboard for account status

4. **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**:

1. Select a provider from dropdown
2. Enter the corresponding API key
3. Save again
4. 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**:

1. **Verify key is still valid**:
   * Go to Account Settings → AI Provider
   * Click "Test API Key"
   * If test fails, key may have been revoked

2. **Check provider account status**:
   * Visit your Claude or OpenAI dashboard
   * Verify billing is current
   * Check for service alerts

3. **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

4. **Re-save settings**:
   * Sometimes helps after provider-side issues
   * Go to Account Settings → AI Provider
   * Test key, then save again

5. **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](../Scoop%20for%20Slack/scoop-for-slack/understanding-scoop-ai.md) - How Scoop's AI works
* [Machine Learning Analytics](../Scoop%20for%20Slack/scoop-for-slack/machine-learning-analytics.md) - AI-powered features

**Provider Support**:

* **Claude**: [Anthropic Documentation](https://docs.anthropic.com)
* **OpenAI**: [OpenAI Documentation](https://platform.openai.com/docs)

**Scoop Support**:

* Email: support@scoopanalytics.com
* 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:

1. **Test your API key** in Account Settings
2. **Check provider status** at your provider's dashboard
3. **Collect information**:
   * Error messages from Scoop
   * Browser console errors (if applicable)
   * Approximate time of issue
   * Provider and account ID
4. **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](#step-1-get-your-api-key) and configure BYOK in minutes.

***

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