Security Best Practices

Follow these security best practices to protect your API keys and prevent unauthorized access.

Never Expose Keys Client-Side

NEVER DO THIS:

// Frontend code - EXPOSED TO USERS!
const client = new BrainusAI({
  apiKey: "brainus_1234567890abcdef", // Visible in browser!
});

DO THIS INSTEAD:

// Frontend: Call your backend
const response = await fetch("/api/query", {
  method: "POST",
  body: JSON.stringify({ query: "Your question" }),
});

// Backend (Node.js): Use environment variable
app.post("/api/query", async (req, res) => {
  const client = new BrainusAI({
    apiKey: process.env.BRAINUS_API_KEY, // Secure!
  });
  const result = await client.query({
    query: req.body.query,
    storeId: "default",
  });
  res.json(result);
});

Use Environment Variables

Never hardcode API keys in your source code.

# .env file (add to .gitignore!)
BRAINUS_API_KEY=brainus_your_key_here

// Load with dotenv
require('dotenv').config();
const { BrainusAI } = require("@brainus/ai");

const client = new BrainusAI({
  apiKey: process.env.BRAINUS_API_KEY
});

# .env file (add to .gitignore!)
BRAINUS_API_KEY=brainus_your_key_here

# Load with python-dotenv
from dotenv import load_dotenv
import os
from brainus_ai import BrainusAI

load_dotenv()

# In async context
# client = BrainusAI(api_key=os.getenv("BRAINUS_API_KEY"))
# async with client...

# Pass as environment variable
docker run -e BRAINUS_API_KEY=brainus_your_key_here myapp

# docker-compose.yml
services:
  app:
    environment:
      BRAINUS_API_KEY: ${BRAINUS_API_KEY}

Add .env to .gitignore

Critical: Never commit API keys to version control!

# .gitignore
.env
.env.local
.env.*.local

If you accidentally commit an API key, revoke it immediately and generate a new one.

Use Different Keys per Environment

Separate keys for each environment:

# Development
BRAINUS_API_KEY_DEV=sk_test_dev_key

# Staging
BRAINUS_API_KEY_STAGING=sk_test_staging_key

# Production
BRAINUS_API_KEY_PROD=brainus_production_key

Benefits:

Isolate usage and quotas
Easier to track which environment caused issues
Limit blast radius if a key is compromised
Revoke dev keys without affecting production

Implement Backend Proxy

Always proxy API requests through your backend:

User → Frontend → Your Backend → BrainUs API
              API key stays here

Why this matters:

API keys never reach the browser
You can add authentication/authorization
Rate limiting on your terms
Logging and monitoring
Cost control

Rotate Keys Regularly

Set up a key rotation schedule:

# Automate with cron
# Rotate production keys every 90 days
0 0 1 */3 * /scripts/rotate-api-keys.sh

Monitor for Suspicious Activity

Watch for unusual patterns:

Sudden spike in requests
Requests from unexpected IPs
High error rates
Unusual query patterns

Enterprise plans include anomaly detection and automatic alerts.

IP Whitelisting (Enterprise)

Restrict API keys to specific IP addresses:

# Only allow requests from these IPs
brainus keys update key_abc123 \
  --allowed-ips "203.0.113.0/24,198.51.100.0/24"

Webhook Signature Verification

If using webhooks, always verify signatures:

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-brainus-signature"];

  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  // Process webhook
});

Security Checklist

Use environment variables for API keys
Add .env to .gitignore
Never expose keys client-side
Implement backend proxy
Use different keys per environment
Rotate keys regularly
Monitor for suspicious activity
Revoke unused keys
Verify webhook signatures

Incident Response

If your key is compromised:

Revoke immediately at Dashboard
Generate new key
Update all services with new key
Review logs for suspicious activity
Contact support at developer@brainus.lk if needed

Report security issues to developer@brainus.lk, not public channels.

Next Steps

Environment Setup - Configure your development environment
Rate Limits - Understanding and handling rate limits

On this page