Authentication

This document outlines the authentication methods for the InsightEmbed API. Proper authentication is required for all API requests to ensure secure access to your account resources.

API Keys

InsightEmbed uses API keys to authenticate requests. You can view and manage your API keys in the Management Portal.

API Key Types

InsightEmbed offers two types of API keys:

1. Primary API Key: Full access to all API endpoints and resources. Should be kept secure and only used in server-side applications.

2. Widget API Key: Limited access designed specifically for widget operations. Can be safely used in client-side code.

Authentication Header

To authenticate an API request, include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request with Authentication

curl -X POST https://api.insightembed.com/v1/analyze/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Content to analyze"}'

Domain Validation

For security purposes, widget API keys are restricted to specific domains. This prevents unauthorized usage of your API quota.

Setting Allowed Domains

You can configure allowed domains in the Management Portal. Wildcards are supported for subdomains:

• example.com - Allows only the exact domain
• *.example.com - Allows all subdomains of example.com
• * - Allows all domains (not recommended for production)

Origin Validation

Requests from the widget include the Origin header, which is validated against your allowed domains. If the origin doesn't match any allowed domain, the request will be rejected with a 403 Forbidden error.

JWT Authentication for Management Portal

The Management Portal uses JWT (JSON Web Tokens) for authentication. This is handled automatically when you log in through the web interface.

JWT Token Lifecycle

1. Obtaining a Token: Log in with your email and password to receive a JWT token
2. Token Expiration: Tokens expire after 24 hours
3. Token Refresh: The system automatically refreshes your token when needed
4. Token Revocation: Logging out invalidates the token

Best Practices

1. Never expose your Primary API Key in client-side code or public repositories

2. Rotate API keys periodically for enhanced security

3. Use environment variables to store API keys in your applications

4. Set specific domain restrictions for widget API keys

5. Implement proper error handling for authentication failures

Error Responses

Status Code	Error Code	Description
401	authentication_error	Missing or invalid API key
403	forbidden	Valid API key but insufficient permissions
403	domain_not_allowed	Request origin not in allowed domains list

Example Error Response

{
  "success": false,
  "error": {
    "code": "domain_not_allowed",
    "message": "The origin 'unauthorized-site.com' is not in your allowed domains list",
    "param": "origin"
  }
}

Rate Limiting

API requests are subject to rate limiting based on your subscription plan. Authentication errors do not count against your rate limits.

Plan	Rate Limit
Free	60 requests per minute
Starter	120 requests per minute
Pro	300 requests per minute

For more information about rate limits, see the API Reference Overview.