Skip to main content

​
API Key Authentication

Brand.dev uses API key authentication to secure all API requests. Every request to the Brand.dev API must include a valid API key in the request headers.

​
Getting Your API Key

1

Sign Up

Create an account at brand.dev if you haven’t already.
2

Access Dashboard

Log in to your Brand.dev dashboard.
3

Copy API Key

Navigate to the API Keys section and copy your API key. Store it securely - it won’t be shown again.
Keep your API key secret! Never commit API keys to version control or expose them in client-side code. Treat them like passwords.

​
Using Your API Key

​
HTTP Header Authentication

Include your API key in the Authorization header with the Bearer prefix: 
curl https://api.brand.dev/v1/brand/retrieve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'

​
SDK Authentication

All official SDKs handle authentication automatically when you provide your API key: 
import BrandDev from "brand.dev";

const client = new BrandDev({
  apiKey: process.env.BRAND_DEV_API_KEY, // Recommended: use environment variables
});

// API key is automatically included in all requests
const { brand } = await client.brand.retrieve({ domain: "stripe.com" });

import brand_dev
import os

client = brand_dev.BrandDev(
    api_key=os.environ.get("BRAND_DEV_API_KEY"),  # Recommended: use environment variables
)

# API key is automatically included in all requests
brand = client.brand.retrieve(domain="stripe.com")

require 'brand_dev'

client = BrandDev::Client.new(
  api_key: ENV['BRAND_DEV_API_KEY']  # Recommended: use environment variables
)

# API key is automatically included in all requests
brand = client.brand.retrieve(domain: 'stripe.com')

​
Storing API Keys Securely

Store your API key in environment variables, never hardcode it in your source code: .env file (for development): 
BRAND_DEV_API_KEY=your_api_key_here
Load in your application: 
// Using dotenv package
import "dotenv/config";

const client = new BrandDev({
  apiKey: process.env.BRAND_DEV_API_KEY,
});

​
Production Deployment

For production environments, set environment variables using your platform’s configuration: Vercel: 
vercel env add BRAND_DEV_API_KEY
Heroku: 
heroku config:set BRAND_DEV_API_KEY=your_api_key_here
Docker: 
docker run -e BRAND_DEV_API_KEY=your_api_key_here your-app
AWS Lambda: Configure environment variables in the Lambda function configuration or use AWS Secrets Manager.
Never commit .env files to version control. Add .env to your .gitignore file: .env .env.local

​
Rate Limiting

Rate limits are applied per API key and vary by plan tier. Below are the current limits and overage rates — see the pricing page for the latest details.
PlanRequests per MonthRequests per SecondOverage
Trial50 one-time trial calls——
Basic2,000 / month2 calls/sec$19 per 1K calls
Pro10,000 / month5 calls/sec$9 per 1K calls
Scale250,000 / month20 calls/sec$6 per 1K calls
EnterpriseCustomCustomContact sales
When you exceed your rate limit, you’ll receive a 429 Too Many Requests response with a Retry-After header.

​
Handling Rate Limits

Implement exponential backoff when you receive rate limit errors: 
async function fetchBrandWithRetry(domain: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const { brand } = await client.brand.retrieve({ domain });
      return brand;
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        // Exponential backoff: wait 2^i seconds
        const delay = Math.pow(2, i) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}
If you consistently hit your limits, consider upgrading your plan on the pricing page or contact support for a custom plan.
Prefetch endpoint is rate-limit free! The Prefetch by Email endpoint doesn’t count against your rate limits or credit usage.

​
Security Best Practices

​
1. Never Expose Keys in Client-Side Code

❌ Bad: Hardcoding API keys in frontend JavaScript 
// DON'T DO THIS!
const client = new BrandDev({
  apiKey: "brand_abc123...", // Exposed in browser
});
✅ Good: Use a backend proxy 
// Frontend: Call your own API
const response = await fetch("/api/brand", {
  method: "POST",
  body: JSON.stringify({ domain: "stripe.com" }),
});

// Backend API route: Use API key server-side
export async function POST(request) {
  const { domain } = await request.json();
  const client = new BrandDev({
    apiKey: process.env.BRAND_DEV_API_KEY, // Secure
  });
  const { brand } = await client.brand.retrieve({ domain });
  return Response.json(brand);
}

​
2. Use HTTPS Only

Always make API requests over HTTPS to encrypt your API key in transit. The Brand.dev API only accepts HTTPS requests.

​
3. Don’t Log API Keys

Avoid logging API keys in application logs or error tracking services: 
// Bad: Logs might contain the API key
console.log("Client config:", client);

// Good: Log only necessary information
console.log("API request for domain:", domain);

​
Testing & Development

​
Local Development

For local development, use a .env.local file that’s not committed to version control: 
# .env.local (gitignored)
BRAND_DEV_API_KEY=your_dev_api_key_here

​
CI/CD Pipelines

Store API keys as secrets in your CI/CD platform:
  • GitHub Actions: Repository Secrets
  • GitLab CI: CI/CD Variables
  • CircleCI: Project Environment Variables

​
Authentication Errors

​
401 Unauthorized

You’ll receive a 401 error if:
  • Your API key is missing from the request
  • Your API key is invalid or expired
  • Your API key has been deleted
Solution: Verify your API key is correct and hasn’t been deleted. 
{
  "status": "error",
  "message": "Invalid API key",
  "code": 401
}

​
403 Forbidden

You’ll receive a 403 error if:
  • Your API key doesn’t have permission for the requested endpoint
  • Your account has been suspended
Solution: Check your account status in the dashboard or contact support.

Quickstart

Get started with your first API call

Core Concepts

Understand Brand.dev fundamentals

Troubleshooting

Common authentication issues

API Reference

Explore all endpoints
Need help with authentication? Contact our team for personalized support.