API Keys

Understand which key is used where in Hunch.

Overview

Hunch uses three different auth models:

• Website API keys for the public widget running on a specific website
• Authenticated user sessions for dashboard, admin, billing, team, and private API actions
• MCP OAuth installations for external AI clients such as ChatGPT or Claude

Each website has its own API key. That key is safe to use in the widget embed because it is scoped to that website deployment.

It is not used for MCP access. External AI clients connect through a separate OAuth-based installation flow.

Finding Your API Key

1. Log in to your Hunch dashboard
2. Navigate to Websites
3. Click on a website
4. Find the Embed Code section
5. Your API key is displayed in the code snippet

The embed code looks like:

<script src="https://cdn.hunchbank.com/embed.js" data-api-key="YOUR_API_KEY"></script>

Using API Keys

Embed Widget

The easiest way to use Hunch is via the embed widget:

<script src="https://cdn.hunchbank.com/embed.js" data-api-key="YOUR_API_KEY"></script>

Programmatic initialization

<script src="https://cdn.hunchbank.com/embed.js"></script>
<script>
  window.Hunch = window.Hunch.init({
    apiKey: 'YOUR_API_KEY',
    widgetTitle: 'Support',
    position: 'right'
  });
</script>

API Key Security

Best Practices

1. Never expose API keys in client-side code for server operations
2. Do not use a website API key for private dashboard routes
3. Keep provider secrets server-side - OpenAI, Anthropic, HubSpot, and similar secrets belong in the dashboard or server, not the public page
4. Use one website key per site - do not reuse the same embed key across unrelated properties

External AI clients and MCP

When you connect Hunch to ChatGPT, Claude, or another remote MCP client:

• do not paste a website API key into that client
• use the website's MCP tab in the Hunch dashboard instead
• authorize access through the Hunch OAuth consent flow
• grant only the scopes you need for that website

Related guides:

• Connect Hunch to ChatGPT
• Connect Hunch to Claude
• External AI Clients

Embed Widget Options

Customization

The embed widget supports various options:

<script>
  window.Hunch = window.Hunch.init({
    apiKey: 'YOUR_API_KEY',
    position: 'right',
    theme: 'auto',
    widgetTitle: 'Support',
    primaryColor: '#000000',
    secondaryColor: '#ffffff'
  });
</script>
<script src="https://cdn.hunchbank.com/embed.js"></script>

Widget Position

Option	Description
bottom-right	Bottom right corner (default)
bottom-left	Bottom left corner

Theme Options

Option	Description
light	Light theme
dark	Dark theme
auto	Match the visitor's system preference

Troubleshooting

401 Unauthorized

• Verify the embed is using the correct website key
• Check that the page belongs to the website you added in Hunch

Widget Not Loading

• Verify API key is correct
• Check browser console for errors
• Ensure JavaScript is enabled
• Verify website URL is added in dashboard

tip

Use website API keys only for the public embed. Private account actions should always go through authenticated user sessions.