Security

CORS & Security Headers

Configure cross-origin resource sharing and security headers for secure browser-based API access.

Origin allowlisting

Security headers

OWASP compliant

How CORS Works

When your frontend makes requests to JustKalm from a browser, the browser sends a preflight OPTIONS request to verify CORS permissions.

CORS Headers Exchange

// Request headers
Origin: https://yourapp.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type

// Response headers (from JustKalm API)
Access-Control-Allow-Origin: https://yourapp.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-Id, X-Idempotency-Key
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: X-Request-Id, X-RateLimit-Remaining, X-RateLimit-Reset

Configuring Allowed Origins

Pattern	Description	Status
`https://yourapp.com`	Exact domain match	Recommended
`https://*.yourapp.com`	Subdomain wildcard	Recommended
`http://localhost:3000`	Local development	Recommended
`*`	All origins (not recommended)	Not recommended
`https://untrusted.com`	Untrusted third-party	Not recommended

Configure via API

# Configure allowed origins via API
curl -X PUT "https://api.justkalm.com/v1/api-keys/ak_live_xxx" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_origins": [
      "https://yourapp.com",
      "https://*.yourapp.com",
      "http://localhost:3000"
    ],
    "allowed_ips": [
      "192.168.1.0/24",
      "10.0.0.0/8"
    ]
  }'

Response Security Headers

JustKalm API responses include these security headers by default:

Header	Value	Purpose
`Strict-Transport-Security`	`max-age=31536000; includeSubDomains; preload`	Enforce HTTPS connections
`X-Content-Type-Options`	`nosniff`	Prevent MIME type sniffing
`X-Frame-Options`	`DENY`	Prevent clickjacking
`X-XSS-Protection`	`1; mode=block`	Enable XSS filter
`Referrer-Policy`	`strict-origin-when-cross-origin`	Control referrer information
`Content-Security-Policy`	`default-src 'self'`	Prevent XSS and injection

Content Security Policy

If your site uses CSP, add these directives to allow JustKalm integration:

Recommended CSP Directives

// Recommended CSP for JustKalm widget integration
Content-Security-Policy: 
  default-src 'self';
  script-src 'self' https://cdn.justkalm.com;
  connect-src 'self' https://api.justkalm.com;
  frame-src https://widget.justkalm.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' https: data:;

Security Best Practices

Use Specific Origins

Always specify exact domains or subdomain patterns. Avoid wildcard (*) origins in production.

Separate Dev/Prod Keys

Use different API keys for development and production with appropriate origin restrictions.

Enable IP Allowlisting

For server-to-server API calls, combine CORS with IP allowlisting for defense in depth.

Never Expose Secret Keys

Secret keys should never be used in browser code. Use publishable keys or server-side proxies.

Troubleshooting CORS Errors

"No 'Access-Control-Allow-Origin' header"

Your origin is not in the allowed list for this API key.

Solution: Add your origin to the API key's allowed_origins list in the dashboard.

"Preflight response has invalid status"

The OPTIONS preflight request is failing or being blocked.

Solution: Ensure your proxy/CDN allows OPTIONS requests and doesn't require authentication for them.

"Credentials flag is true but Allow-Credentials is false"

Credentials mode mismatch between request and response.

Solution: JustKalm supports credentials. Ensure you're using a specific origin (not *) in your allowed origins.

Configure Security Settings

Manage CORS and security settings in your dashboard.

Open Dashboard