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
• Public AI connector URLs for visitor access from ChatGPT, Claude, or another compatible client

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 Public AI Access. External AI visitors use the public connector URL from the website's Public AI Access tab.

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

Public AI Access

When you make a Hunch-enabled website usable from ChatGPT, Claude, or another compatible AI client:

• do not paste a website API key into that client
• use the website's Public AI Access tab in the Hunch dashboard instead
• turn on Unlisted or Listed public access intentionally
• share the public connector URL, not the embed API key
• review Website Action Controls before sharing the connector

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.