InsightEmbed Docs

Appearance

API Key Management ​

This document explains how to create, manage, and secure API keys for the InsightEmbed platform through the Management Portal.

API Keys Overview ​

API keys are essential credentials that authenticate your requests to the InsightEmbed API and widget. Proper management of these keys is crucial for security and functionality.

Types of API Keys ​

InsightEmbed offers two types of API keys, each with different access levels and intended uses:

Primary API Key ​

  • Purpose: Used for server-side API calls and full administrative access
  • Access Level: Full access to all API endpoints and resources
  • Security: Should be kept strictly confidential and only used in secure server environments
  • Usage: Backend integrations, custom implementations, and administrative tasks

Widget API Key ​

  • Purpose: Used specifically for widget initialization on websites
  • Access Level: Limited access to only widget-related endpoints
  • Security: Can be safely used in client-side code with proper domain restrictions
  • Usage: Embedding the widget on websites and web applications

Accessing API Key Management ​

To access the API key management section:

  1. Log in to the InsightEmbed Management Portal
  2. Navigate to Settings > API Keys in the main navigation menu
  3. The API Keys page displays all your current API keys

Creating API Keys ​

Creating a Primary API Key ​

To create a new Primary API Key:

  1. Navigate to Settings > API Keys
  2. Click the Create API Key button
  3. Select Primary API Key as the key type
  4. Enter a descriptive name for the key (e.g., "Production Backend")
  5. Click Create Key
  6. Your new API key will be displayed once - make sure to copy and store it securely
  7. Click I've Saved My Key to confirm

Creating a Widget API Key ​

To create a new Widget API Key:

  1. Navigate to Settings > API Keys
  2. Click the Create API Key button
  3. Select Widget API Key as the key type
  4. Enter a descriptive name for the key (e.g., "Company Blog Widget")
  5. Configure domain restrictions (see Domain Restrictions section)
  6. Click Create Key
  7. Your new API key will be displayed once - make sure to copy and store it securely
  8. Click I've Saved My Key to confirm

Managing API Keys ​

Viewing API Keys ​

The API Keys page displays a list of all your API keys with the following information:

  • Key name
  • Key type (Primary or Widget)
  • Creation date
  • Last used date
  • Status (Active or Revoked)
  • Domain restrictions (for Widget API Keys)

For security reasons, the full API key is never displayed after initial creation.

Renaming API Keys ​

To rename an existing API key:

  1. Navigate to Settings > API Keys
  2. Find the API key you want to rename
  3. Click the Edit button (pencil icon)
  4. Update the name field
  5. Click Save Changes

Revoking API Keys ​

If an API key is compromised or no longer needed, you should revoke it immediately:

  1. Navigate to Settings > API Keys
  2. Find the API key you want to revoke
  3. Click the Revoke button
  4. Confirm the revocation

Once revoked, an API key cannot be reactivated. You'll need to create a new key if needed.

Domain Restrictions ​

Domain restrictions are a critical security feature for Widget API Keys that limit which websites can use the key.

Setting Domain Restrictions ​

When creating or editing a Widget API Key, you can set domain restrictions:

  1. In the Domain Restrictions section, add the domains where the widget will be used
  2. Enter one domain per line
  3. Click Add Domain after each entry

Domain Format Options ​

You can specify domains in several formats:

  • Exact domain: example.com - Matches only this exact domain
  • Subdomain wildcard: *.example.com - Matches any subdomain of example.com
  • Development domains: localhost, 127.0.0.1 - For local development
  • All domains: * - Allows any domain (not recommended for production)

Editing Domain Restrictions ​

To modify domain restrictions for an existing Widget API Key:

  1. Navigate to Settings > API Keys
  2. Find the Widget API Key you want to update
  3. Click the Edit button
  4. Modify the domain list as needed
  5. Click Save Changes

API Key Usage Tracking ​

The Management Portal provides insights into how your API keys are being used:

Viewing Usage Statistics ​

To view usage statistics for a specific API key:

  1. Navigate to Settings > API Keys
  2. Find the API key you want to analyze
  3. Click the View Usage button
  4. The usage page shows:
    • Total requests over time
    • Requests by endpoint
    • Error rates
    • Usage by domain (for Widget API Keys)

Usage Alerts ​

Set up alerts for unusual API key activity:

  1. Navigate to Settings > Notifications
  2. Scroll to the API Key Alerts section
  3. Configure alerts for:
    • Unusual request volume
    • High error rates
    • New domain usage
    • Failed authentication attempts
  4. Select notification methods (email, in-app)
  5. Click Save Notification Settings

API Key Security Best Practices ​

Securing Primary API Keys ​

  1. Never expose in client-side code: Primary API Keys should never be included in JavaScript, HTML, or any client-accessible code

  2. Use environment variables: Store API keys in environment variables rather than hardcoding them

  3. Restrict access: Limit which team members have access to Primary API Keys

  4. Regular rotation: Rotate Primary API Keys periodically (e.g., every 90 days)

  5. Separate keys for environments: Use different keys for development, staging, and production environments

Securing Widget API Keys ​

  1. Set specific domain restrictions: Always limit Widget API Keys to only the domains where they'll be used

  2. Avoid wildcard domains in production: Use specific domains rather than wildcard patterns when possible

  3. Monitor usage: Regularly review the usage patterns of your Widget API Keys

  4. Create purpose-specific keys: Use separate Widget API Keys for different websites or applications

Troubleshooting ​

Authentication Errors ​

If you're experiencing authentication errors:

  1. Verify that you're using the correct API key type for your use case
  2. Check that the API key hasn't been revoked
  3. For Widget API Keys, ensure the domain making the request is in the allowed domains list
  4. Verify that the API key is being sent correctly in the Authorization header

Domain Restriction Issues ​

If your widget isn't working due to domain restrictions:

  1. Check that the exact domain of your website is in the allowed domains list
  2. Remember that subdomains need to be explicitly allowed or covered by a wildcard
  3. For local development, ensure localhost is in the allowed domains
  4. Check for protocol mismatches (http vs https)

Frequently Asked Questions ​

Q: How many API keys can I create?

A: There is no strict limit on the number of API keys you can create, but we recommend creating only as many as you need to maintain good security practices.

Q: Can I temporarily disable an API key instead of revoking it?

A: Currently, API keys can only be active or revoked. If you need to temporarily disable access, we recommend revoking the current key and creating a new one when access needs to be restored.

Q: Are there rate limits associated with API keys?

A: Yes, API keys are subject to rate limits based on your subscription plan. These limits are shared across all your API keys. See the API Reference Overview for details.

Q: What happens if my API key is compromised?

A: If you suspect an API key has been compromised, you should:

  1. Immediately revoke the compromised key
  2. Create a new API key to replace it
  3. Update your applications with the new key
  4. Review your account for any unauthorized activity

Q: Can I use the same Widget API Key on multiple websites?

A: Yes, you can use the same Widget API Key on multiple websites by adding all the domains to the allowed domains list. However, for better security and usage tracking, we recommend using separate keys for different websites.

Additional Resources ​

© 2026 InsightEmbed