API Keys - Brand DNA

Overview

API Keys enable programmatic access to Brand DNA’s features. Automate brand analyses, integrate with your existing tools, and build custom workflows—all through our RESTful API.

Pro/Agency Tier Only — API access requires a Pro or Agency subscription. See API Reference for full documentation.

What You Can Do with the API

Run Analyses

Programmatically analyze brands and retrieve results

Chat with Helix

Send messages to Helix AI and receive responses

Manage Workspace

Create, update, and retrieve workspace tasks

Track Competitors

Monitor competitor changes and receive alerts (Pro/Agency)

Export Reports

Generate and download PDF reports programmatically

Team Management

Add/remove team members and manage permissions (Agency)

Creating API Keys

Navigate to API Keys

Settings → API Keys → Create New Key

Name Your Key

Descriptive name (e.g., “Production Server”, “Testing”, “CI/CD Pipeline”)

Copy & Secure

Copy key immediately (shown only once) and store securely

Security Critical: API keys are shown only once. If you lose a key, you must delete it and create a new one. Store keys in a password manager or secrets vault.

API Key Permissions

Scope Definitions

Scope	Capabilities	Use Cases
`read:analyses`	Retrieve analysis results, history, and metadata	Dashboards, reporting tools
`write:analyses`	Run new brand analyses	Automation, batch processing
`read:chat`	Retrieve Helix chat history	Audit logs, conversation backups
`write:chat`	Send messages to Helix AI	Chatbots, integrations
`read:workspace`	View tasks and workspace data	Project management tools
`write:workspace`	Create, update, delete tasks	Task automation
`read:competitors`	Retrieve competitor tracking data	Analytics dashboards
`write:competitors`	Add/remove tracked competitors	Automated monitoring
`read:exports`	Download PDF exports	Report delivery systems
`write:exports`	Generate new exports	Automated reporting
`admin:team`	Manage team members (Agency only)	Provisioning automation
`admin:full`	All permissions (equivalent to Owner access)	Internal tools, testing

Recommended Permission Sets

Production Server (Minimal Permissions)

Scopes: read:analyses, write:analyses, read:exportsUse Case: Public-facing application that runs analyses and displays resultsWhy Minimal: Reduces risk if key is compromised

Internal Dashboard (Read-Only)

Scopes: read:analyses, read:workspace, read:competitorsUse Case: Internal analytics dashboard showing team performanceWhy Read-Only: No accidental data modification

Automation Pipeline (Write Access)

Scopes: write:analyses, write:workspace, write:exportsUse Case: Nightly batch analysis and report generationWhy Write: Needs to create resources, but not delete

CI/CD Testing (Full Access)

Scopes: admin:fullUse Case: Automated testing in development environmentWhy Full: Needs to test all API endpoints

Managing API Keys

Current API Keys

Example API key roster:

Name	Scopes	Created	Last Used	Status	Actions
Production Server	read:analyses, write:analyses	Jan 15, 2026	2 min ago	Active ✅	Revoke
Internal Dashboard	read:*	Dec 1, 2025	1 hour ago	Active ✅	Revoke
Testing	admin:full	Jan 20, 2026	3 days ago	Active ✅	Revoke
Old CI Pipeline	admin:full	Nov 10, 2025	45 days ago	Inactive ⚠️	Revoke

Revoking API Keys

Find Key to Revoke

Settings → API Keys → Locate key

Click Revoke

Click Revoke next to key

Confirm Revocation

Confirm action (cannot be undone)

Access Denied

Key invalidated immediately; API requests return 401 Unauthorized

Security Hygiene: Revoke unused keys regularly. If “Last Used” is over 30 days ago, consider revoking.

Rotating API Keys

Best practice: Rotate keys every 90 days

Create New Key

Generate new key with same permissions as old key

Update Applications

Replace old key with new key in all applications/scripts

Test New Key

Verify all integrations work with new key

Revoke Old Key

After 24-48 hours, revoke old key to ensure smooth transition

Using API Keys

Authentication

All API requests require authentication via Bearer token:

curl https://api.branddna.app/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Headers:

Authorization: Bearer YOUR_API_KEY (required)
Content-Type: application/json (for POST/PUT requests)

Example: Run Brand Analysis

const fetch = require('node-fetch');

const API_KEY = 'your_api_key_here';
const API_URL = 'https://api.branddna.app/v1/analyze';

async function analyzeBrand(url) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: url,
      type: 'full' // or 'flash'
    })
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.statusText}`);
  }

  const data = await response.json();
  return data;
}

analyzeBrand('https://example.com')
  .then(result => console.log(result))
  .catch(error => console.error(error));

See API Reference for complete documentation.

Rate Limits

API rate limits by tier:

Tier	Requests/Minute	Requests/Hour	Requests/Day
Pro	60	1,000	10,000
Agency	120	5,000	50,000

Headers Returned:

X-RateLimit-Limit: Total requests allowed per window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets

429 Too Many Requests: If you exceed rate limit, requests return 429 with:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded 60 requests per minute",
  "retry_after": 45
}

Handling Rate Limits:

Implement exponential backoff
Cache responses when possible
Use webhooks for long-running operations instead of polling

Need Higher Limits? Contact enterprise@branddna.app for custom rate limits.

Security Best Practices

1. Store Keys Securely

Never commit API keys to version control (Git, SVN, etc.). Use environment variables or secrets managers.

Good:

# .env file (add to .gitignore)
BRAND_DNA_API_KEY=sk_live_abc123...

# Load in application
require('dotenv').config();
const apiKey = process.env.BRAND_DNA_API_KEY;

Bad:

// ❌ Hardcoded in source code
const apiKey = 'sk_live_abc123...';

2. Use Environment-Specific Keys

Development: Separate key for local development
Staging: Different key for staging environment
Production: Production-only key with minimal permissions

Benefits:

Revoke development key without affecting production
Track usage by environment
Limit blast radius if key is compromised

3. Rotate Keys Regularly

Every 90 days: Proactive rotation
Immediately: If key may have been exposed (e.g., accidentally committed)
After employee departure: Revoke keys former team members had access to

4. Use Minimal Permissions

Only grant scopes that are actually needed: Example: Dashboard that displays analysis results

✅ Grant: read:analyses
❌ Don’t grant: write:analyses, admin:full

5. Monitor Key Usage

Review “Last Used” column regularly:

Keys unused for 30+ days should be investigated
Unexpected usage patterns may indicate compromise
Set up alerts for API errors (401, 403, 429)

Webhooks (Alternative to Polling)

Instead of polling the API, use webhooks for event notifications: Example: Analysis Complete Webhook

POST https://your-server.com/webhooks/brand-dna
{
  "event": "analysis.completed",
  "timestamp": "2026-01-27T14:23:45Z",
  "data": {
    "analysis_id": "anl_abc123",
    "url": "https://example.com",
    "status": "completed",
    "results_url": "https://api.branddna.app/v1/analyses/anl_abc123"
  }
}

See Webhooks for setup instructions.

API Key Quotas

API usage counts toward your plan quotas:

Pro Plan

Resource	Quota	API Access
Analyses	Unlimited	✅ Create via API
Flash Audits	Unlimited	✅ Create via API
Helix Messages	Unlimited	✅ Send via API
Exports	Unlimited	✅ Generate via API

Agency Plan

Resource	Quota	API Access
Analyses	Unlimited	✅ Create via API
Flash Audits	Unlimited	✅ Create via API
Helix Messages	Unlimited	✅ Send via API
Exports	Unlimited	✅ Generate via API
Team Management	10 seats included	✅ Manage via API

API requests count toward the same quotas as web interface usage.

Troubleshooting

401 Unauthorized

Cause: Invalid or missing API key Solutions:

Verify key is correct (no extra spaces)
Check key hasn’t been revoked
Ensure Authorization: Bearer header is present

403 Forbidden

Cause: Valid key, but insufficient permissions Solutions:

Check key scopes (Settings → API Keys)
Create new key with required permissions
Verify account tier supports requested feature

429 Rate Limit Exceeded

Cause: Too many requests in time window Solutions:

Implement exponential backoff
Reduce request frequency
Cache responses
Upgrade to Agency tier for higher limits

500 Internal Server Error

Cause: Server-side issue Solutions:

Retry request after 5-10 seconds
Check status page
Contact support if persistent

API Reference - Complete API documentation
Settings - Account preferences
Billing - Upgrade for API access
Teams - Team API key management (Agency)

API questions? Email api@branddna.app or see API Documentation.

Get Started

AI Features

Dashboard Sections

Account & Teams

API Reference

Legal

​Overview

​What You Can Do with the API

Run Analyses

Chat with Helix

Manage Workspace

Track Competitors

Export Reports

Team Management

​Creating API Keys

​API Key Permissions

​Scope Definitions

​Recommended Permission Sets

​Managing API Keys

​Current API Keys

​Revoking API Keys

​Rotating API Keys

​Using API Keys

​Authentication

​Example: Run Brand Analysis

​Rate Limits

​Security Best Practices

​1. Store Keys Securely

​2. Use Environment-Specific Keys

​3. Rotate Keys Regularly

​4. Use Minimal Permissions

​5. Monitor Key Usage

​Webhooks (Alternative to Polling)

​API Key Quotas

​Pro Plan

​Agency Plan

​Troubleshooting

​401 Unauthorized

​403 Forbidden

​429 Rate Limit Exceeded

​500 Internal Server Error

​Related Pages

Overview

What You Can Do with the API

Creating API Keys

API Key Permissions

Scope Definitions

Recommended Permission Sets

Managing API Keys

Current API Keys

Revoking API Keys

Rotating API Keys

Using API Keys

Authentication

Example: Run Brand Analysis

Rate Limits

Security Best Practices

1. Store Keys Securely

2. Use Environment-Specific Keys

3. Rotate Keys Regularly

4. Use Minimal Permissions

5. Monitor Key Usage

Webhooks (Alternative to Polling)

API Key Quotas

Pro Plan

Agency Plan

Troubleshooting

401 Unauthorized

403 Forbidden

429 Rate Limit Exceeded

500 Internal Server Error

Related Pages