What Is a Widget Key?

2026-03-02 · Guide

Every MediaSFU widget — whether it's a Click-to-Call button, an AI agent, or a full meeting portal — requires a Widget Key to function. Think of it as a scoped API token specifically designed for client-side embeds.

Why Widget Keys Are Safe in Client-Side Code

Traditional API keys are dangerous in client code because they grant broad access. Widget keys are different:

A widget key only works on the domains you authorize. Even if someone copies the key from your page source and puts it on their site — it won't work. The MediaSFU CDN checks the requesting origin before initializing.

A Click-to-Call key can't be used to spin up an AI Agent session. Each key is tied to a specific widget type and configuration profile.

Every key has built-in rate limiting. If someone tries to abuse a key (e.g., automated flood of call attempts), the system throttles and eventually blocks that key until you investigate.

Keys are cheap to create and cheap to revoke. If anything looks wrong, generate a new key, update your embed, and the old key becomes useless. There's no "master key" situation.

Creating Your First Widget Key

Here's the step-by-step:

1. Log in to your MediaSFU dashboard
2. Navigate to Widgets in the sidebar
3. Click Create Widget
4. Choose your widget type (Call Button, AI Agent, Meeting Portal, Web Agent, Calls Dashboard, or Agents Dashboard)
5. Configure the widget — appearance, behavior, connected phone numbers or AI agents
6. Click Generate Key
7. Copy the embed snippet

The snippet looks like this:

<script src="https://cdn.mediasfu.com/widget.js" async></script>
<mediasfu-call-button
  widget-key="wk_abc123def456"
  button-text="Talk to Sales"
  primary-color="#6366f1"
  theme="dark"
  position="bottom-right">
</mediasfu-call-button>

That's your entire integration. Paste it before </body> and you're live.

The Localhost Development Workflow

Every new widget key works on localhost by default. This is intentional — we want you to be able to develop and test without friction.

During development:

• Keys work on localhost, 127.0.0.1, and localhost:* (any port)
• All widget features function identically to production
• Call routing, AI agent responses, meeting creation — everything is real
• Usage still counts against your account (be mindful during heavy testing)

Locking Down for Production

When you're ready to go live, update the key's domain restrictions:

Dashboard → Widgets → [Your Widget] → Settings → Allowed Domains

Add your production domain(s):

yourdomain.com
www.yourdomain.com
app.yourdomain.com

You can add multiple domains. Subdomains need to be listed explicitly — yourdomain.com does not automatically cover app.yourdomain.com.

After adding domains:

• The widget will only work on those listed domains
• localhost access is removed unless you explicitly keep it in the list
• Unauthorized origins get a silent failure (no console errors, no visible feedback)

Managing Multiple Widget Keys

Most real deployments use several keys:

Each key has independent analytics, so you can see usage broken down by environment and purpose.

Public-Facing vs. Internal Widgets

This distinction matters for security planning:

Public-facing widgets Public

Click-to-Call, AI Agent, Meeting Portal, Web Agent

• Embedded on pages accessible to anyone
• Domain-locked to your public site
• Rate-limited per visitor (IP-based)
• Designed to handle anonymous, untrusted traffic
• Self-healing — if an AI agent session crashes, the widget auto-recovers

Internal widgets Internal

Calls Dashboard, Agents Dashboard

• Embedded behind your authentication layer
• Domain-locked to internal domains (admin.*, ops.*, etc.)
• Display sensitive operational data
• Should never be on a publicly accessible page
• Pair with your own RBAC (role-based access control) for who sees what

Key Rotation and Security Hygiene

Best practices for ongoing security:

1. Rotate keys periodically

Even if nothing is wrong, rotate production keys every 90 days. Create a new key with the same configuration, update your embed, verify it works, then revoke the old key.

2. Use different keys per environment

Dev, staging, production — each should have its own key. This prevents dev testing from polluting production analytics and limits blast radius if a key leaks.

3. Monitor usage dashboards

Unusual spikes in call volume or AI sessions could indicate key abuse. Set up alerts if available.

4. Revoke immediately on breach

If you suspect a key has been exposed (e.g., committed to a public GitHub repo), revoke it immediately. Generate a new one. The transition takes seconds.

5. Keep embed codes in environment variables

If you're using React, Vue, or similar:

<mediasfu-call-button
  widget-key={process.env.REACT_APP_WIDGET_KEY}
  ...
/>

This way the key lives in .env and isn't hardcoded in your source repository. The key is still visible in the rendered HTML — that's fine because it's domain-locked — but it's not in your Git history.

What Happens When a Key Is Revoked?

When you revoke a widget key:

1. The widget stops initializing on all domains within ~60 seconds (CDN cache TTL)
2. No new calls, sessions, or meetings can be created with that key
3. Active calls or sessions already in progress are not interrupted — they complete normally
4. Usage data for the revoked key remains in your dashboard for auditing
5. The key ID is permanently retired and cannot be reused

Pricing and Usage

There's no separate "widget fee." The widgets are a delivery mechanism; you pay for the underlying communication services they consume.

Getting Started Today

1. Log in to mediasfu.com
2. Navigate to Widgets
3. Create your first widget — we recommend starting with Click-to-Call (simplest to test)
4. Paste the embed on a local HTML file and open it
5. Make a test call
6. When ready, add your domain and deploy

Have questions about widget keys or security? Reach out to our team or try the AI support agent right on our demos page.