Authentication

Overview

Brand DNA API uses API keys for authentication. All requests must include a valid API key in the Authorization header.

Creating API Keys

Upgrade to Pro/Agency

API access requires Pro or Agency tier

Navigate to API Keys

Settings → API Keys → Create New Key

Name and Scope

Give key a descriptive name
Select permissions (scopes)

Copy Key

Copy and securely store key (shown only once)

See API Keys for detailed management.

Authentication Method

Bearer Token

Include API key in Authorization header:

curl https://api.branddna.app/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Header Format:

Authorization: Bearer sk_live_abc123xyz...

API Key Format

API keys follow this pattern:

Production: sk_live_ + 32 alphanumeric characters
Test: sk_test_ + 32 alphanumeric characters

Example:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Permissions (Scopes)

API keys support granular permissions:

Scope	Read	Write	Description
`read:analyses`	✅	—	Retrieve analysis results and history
`write:analyses`	—	✅	Run new brand analyses
`read:chat`	✅	—	Retrieve Helix chat history
`write:chat`	—	✅	Send messages to Helix AI
`read:workspace`	✅	—	View tasks and workspace data
`write:workspace`	—	✅	Create, update, delete tasks
`read:competitors`	✅	—	Retrieve competitor data
`write:competitors`	—	✅	Add/remove tracked competitors
`read:exports`	✅	—	Download PDF exports
`write:exports`	—	✅	Generate new exports
`admin:team`	✅	✅	Manage team members (Agency only)
`admin:full`	✅	✅	All permissions

Checking Required Scopes

Each endpoint specifies required scopes in documentation: Example: POST /v1/analyze

Required Scopes: write:analyses
403 Forbidden if key lacks this scope

Making Authenticated Requests

cURL Example

curl https://api.branddna.app/v1/analyses \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

JavaScript/Node.js Example

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

const API_KEY = process.env.BRAND_DNA_API_KEY;
const BASE_URL = 'https://api.branddna.app/v1';

async function makeRequest(endpoint, method = 'GET', body = null) {
  const options = {
    method,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  };

  if (body) {
    options.body = JSON.stringify(body);
  }

  const response = await fetch(`${BASE_URL}${endpoint}`, options);

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.json();
}

// Usage
makeRequest('/analyses')
  .then(data => console.log(data))
  .catch(error => console.error(error));

Python Example

import os
import requests

API_KEY = os.environ['BRAND_DNA_API_KEY']
BASE_URL = 'https://api.branddna.app/v1'

def make_request(endpoint, method='GET', data=None):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }

    url = f'{BASE_URL}{endpoint}'
    response = requests.request(method, url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# Usage
analyses = make_request('/analyses')
print(analyses)

PHP Example

<?php

$apiKey = getenv('BRAND_DNA_API_KEY');
$baseUrl = 'https://api.branddna.app/v1';

function makeRequest($endpoint, $method = 'GET', $data = null) {
    global $apiKey, $baseUrl;

    $options = [
        'http' => [
            'method' => $method,
            'header' => [
                "Authorization: Bearer $apiKey",
                'Content-Type: application/json'
            ]
        ]
    ];

    if ($data) {
        $options['http']['content'] = json_encode($data);
    }

    $context = stream_context_create($options);
    $response = file_get_contents("$baseUrl$endpoint", false, $context);
    return json_decode($response, true);
}

// Usage
$analyses = makeRequest('/analyses');
var_dump($analyses);

Error Responses

401 Unauthorized

Missing or invalid API key:

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Common Causes:

API key missing from Authorization header
API key has been revoked
Typo in API key (extra spaces, incorrect format)

403 Forbidden

Valid key, but insufficient permissions:

{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scope: write:analyses",
  "code": "INSUFFICIENT_PERMISSIONS",
  "required_scopes": ["write:analyses"],
  "current_scopes": ["read:analyses"]
}

Solution:

Create new API key with required scopes
Or update existing key permissions (Settings → API Keys)

Security Best Practices

1. Store Keys Securely

Never hardcode API keys in source code or commit to version control.

Good: Environment Variables

# .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

// ❌ NEVER DO THIS
const apiKey = 'sk_live_abc123...';

2. Use HTTPS Only

All API requests MUST use HTTPS:

✅ https://api.branddna.app/v1/analyze
❌ http://api.branddna.app/v1/analyze

Requests to HTTP endpoints will be rejected.

3. Rotate Keys Regularly

Best Practice: Rotate API keys every 90 days

Create New Key

Generate new key with same permissions

Update Applications

Replace old key in all environments

Test

Verify all integrations work

Revoke Old Key

After 24-48 hours, revoke old key

4. Use Minimal Permissions

Only grant scopes your application needs: Example: Dashboard displaying analysis results

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

5. Separate Keys per Environment

Use different API keys for:

Development: sk_test_ keys for local testing
Staging: Separate key for staging environment
Production: Production-only key with minimal scopes

Benefits:

Revoke dev key without affecting production
Track usage by environment
Limit damage if key is compromised

6. Monitor Key Usage

Regularly review API key activity:

Settings → API Keys → Last Used column
Investigate keys unused for 30+ days
Revoke unused or suspicious keys

API Key Lifecycle

Active Key

Status: Active ✅
Created: Jan 15, 2026
Last Used: 2 minutes ago

Behavior: All requests succeed (assuming correct scopes)

Revoked Key

Status: Revoked ❌
Created: Jan 15, 2026
Revoked: Jan 27, 2026
Last Used: Jan 26, 2026

Behavior:

All requests return 401 Unauthorized
Cannot be reactivated (must create new key)

Test vs. Production Keys

Test Keys (`sk_test_`)

Purpose: Testing and development Behavior:

Access sandbox environment: https://sandbox-api.branddna.app/v1
No rate limits
Data deleted after 7 days
Doesn’t count toward production quotas

Usage:

curl https://sandbox-api.branddna.app/v1/analyze \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json"

Production Keys (`sk_live_`)

Purpose: Production applications Behavior:

Access production environment: https://api.branddna.app/v1
Rate limits enforced
Data persisted according to plan
Counts toward quotas

Usage:

curl https://api.branddna.app/v1/analyze \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

Use test keys during development, production keys for live applications.

Troubleshooting

API Key Not Working

Check:

Key format correct: sk_live_ or sk_test_ + 32 chars
No extra spaces or line breaks
Key hasn’t been revoked (Settings → API Keys)
Subscription is active (billing issue can disable API)

Permission Errors

403 Forbidden:

Check required scopes for endpoint in docs
Verify key has those scopes (Settings → API Keys)
Create new key with correct permissions

Rate Limit Issues

429 Too Many Requests:

Check X-RateLimit-Remaining header
Implement exponential backoff
Upgrade to Agency for higher limits

API Overview - Getting started with the API
API Keys - Manage keys and permissions
Analysis API - Run brand analyses
Rate Limits - Request limits by tier

Authentication configured? Continue to Analysis API →

Get Started

AI Features

Dashboard Sections

Account & Teams

API Reference

Legal

Overview

Creating API Keys

Authentication Method

Bearer Token

API Key Format

Permissions (Scopes)

Checking Required Scopes

Making Authenticated Requests

cURL Example

JavaScript/Node.js Example

Python Example

PHP Example

Error Responses

401 Unauthorized

403 Forbidden

Security Best Practices

1. Store Keys Securely

2. Use HTTPS Only

3. Rotate Keys Regularly

4. Use Minimal Permissions

5. Separate Keys per Environment

6. Monitor Key Usage

API Key Lifecycle

Active Key

Revoked Key

Test vs. Production Keys

Test Keys (`sk_test_`)

Production Keys (`sk_live_`)

Troubleshooting

API Key Not Working

Permission Errors

Rate Limit Issues

Get Started

AI Features

Dashboard Sections

Account & Teams

API Reference

Legal

​Overview

​Creating API Keys

​Authentication Method

​Bearer Token

​API Key Format

​Permissions (Scopes)

​Checking Required Scopes

​Making Authenticated Requests

​cURL Example

​JavaScript/Node.js Example

​Python Example

​PHP Example

​Error Responses

​401 Unauthorized

​403 Forbidden

​Security Best Practices

​1. Store Keys Securely

​2. Use HTTPS Only

​3. Rotate Keys Regularly

​4. Use Minimal Permissions

​5. Separate Keys per Environment

​6. Monitor Key Usage

​API Key Lifecycle

​Active Key

​Revoked Key

​Test vs. Production Keys

​Test Keys (sk_test_)

​Production Keys (sk_live_)

​Troubleshooting

​API Key Not Working

​Permission Errors

​Rate Limit Issues

​Related Pages

Overview

Creating API Keys

Authentication Method

Bearer Token

API Key Format

Permissions (Scopes)

Checking Required Scopes

Making Authenticated Requests

cURL Example

JavaScript/Node.js Example

Python Example

PHP Example

Error Responses

401 Unauthorized

403 Forbidden

Security Best Practices

1. Store Keys Securely

2. Use HTTPS Only

3. Rotate Keys Regularly

4. Use Minimal Permissions

5. Separate Keys per Environment

6. Monitor Key Usage

API Key Lifecycle

Active Key

Revoked Key

Test vs. Production Keys

Test Keys (`sk_test_`)

Production Keys (`sk_live_`)

Troubleshooting

API Key Not Working

Permission Errors

Rate Limit Issues

Related Pages