Authentication

All AIBeam API requests require authentication using an API key. This guide covers how to create keys, use them in requests, and follow security best practices.

Getting Your API Key

API keys are available to Professional and Agency subscribers. If you're on a Starter plan, upgrade to access the API.

Create an API Key

1. Log in to your AIBeam account
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Enter a descriptive Name (e.g., "Production Dashboard Integration") and optional Description
5. Click Create
6. Copy your API key immediately — it will only be shown once

Store your key securely. Anyone with your key can access the AIBeam API as your account.

Key Management

Each account can have multiple active API keys. You can:

• Name your keys — Use descriptive names to track which app uses each key
• View last used date — See when each key was last used
• Revoke keys — Immediately deactivate a key in Settings
• View request count — Monitor API usage per key

Making Authenticated Requests

All API requests require the Authorization header with your API key in Bearer format:

Authorization: Bearer YOUR_API_KEY

cURL

curl -H "Authorization: Bearer $AIBEAM_API_KEY" \
  https://aibeam.io/api/v1/projects

Store your API key in an environment variable:

export AIBEAM_API_KEY="your_actual_key_here"

curl -H "Authorization: Bearer $AIBEAM_API_KEY" \
  https://aibeam.io/api/v1/projects

JavaScript / TypeScript

const apiKey = process.env.AIBEAM_API_KEY;

const response = await fetch('https://aibeam.io/api/v1/projects', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data.data);

With a library like axios:

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://aibeam.io/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.AIBEAM_API_KEY}`
  }
});

const projects = await client.get('/projects');
console.log(projects.data.data);

Python

import os
import requests

api_key = os.getenv('AIBEAM_API_KEY')

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://aibeam.io/api/v1/projects',
    headers=headers
)

data = response.json()
print(data['data'])

Using the httpx library (async-friendly):

import httpx
import os

api_key = os.getenv('AIBEAM_API_KEY')

async with httpx.AsyncClient() as client:
    response = await client.get(
        'https://aibeam.io/api/v1/projects',
        headers={'Authorization': f'Bearer {api_key}'}
    )
    data = response.json()
    print(data['data'])

Node.js + TypeScript

import fetch from 'node-fetch';

interface ProjectResponse {
  data: Array<{
    id: string;
    name: string;
    brand_name: string;
    website_url: string;
  }>;
}

async function getProjects(): Promise<ProjectResponse> {
  const response = await fetch('https://aibeam.io/api/v1/projects', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.AIBEAM_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

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

  return response.json();
}

Security Best Practices

Follow these best practices to keep your API keys secure:

1. Use Environment Variables

Never hardcode API keys in your source code. Always use environment variables:

# .env (never commit this file)
AIBEAM_API_KEY=your_key_here

import os
api_key = os.getenv('AIBEAM_API_KEY')

Add .env to your .gitignore:

.env
.env.local
.env.*.local

2. Rotate Keys Regularly

Rotate API keys every 90 days or after any suspected compromise:

1. Create a new API key in Settings
2. Update all services to use the new key
3. Wait a few minutes to ensure all traffic has switched
4. Revoke the old key in Settings

3. Use Minimal Permissions

If your platform supports key-level permissions (coming soon), use the minimum required permissions for each key. For now:

• Create separate keys for different environments (staging vs. production)
• Create separate keys for different applications or integrations
• Use descriptive names so you can identify unused keys

4. Monitor Key Usage

Check the "Last Used" date on your API keys in Settings. Revoke any keys that haven't been used recently or that you no longer recognize.

5. Revoke Compromised Keys Immediately

If you believe an API key has been compromised:

1. Log in to your AIBeam account immediately
2. Go to Settings → API Keys
3. Click Revoke on the compromised key
4. Create a new API key
5. Update all services to use the new key

Revocation is immediate — the old key will no longer work.

6. Never Share Keys

Don't share API keys via:

• Email
• Chat applications
• Code repositories (even private ones)
• Documentation or tickets

7. Secure Your Secrets in CI/CD

If using CI/CD pipelines, store API keys as secrets:

GitHub Actions:

env:
  AIBEAM_API_KEY: ${{ secrets.AIBEAM_API_KEY }}

GitLab CI:

AIBEAM_API_KEY:
  variables:
    AIBEAM_API_KEY: $AIBEAM_API_KEY

CircleCI:

environment:
  AIBEAM_API_KEY: $AIBEAM_API_KEY

Subscription Requirements

API access requires a Professional or Agency subscription:

If you're on a Starter plan and need API access, upgrade your subscription in the Billing section.

Troubleshooting

"Unauthorized" Error

If you receive HTTP 401 (Unauthorized):

• Verify your API key is correct (no typos, spaces, or extra characters)
• Confirm the header format: Authorization: Bearer YOUR_KEY (note the space)
• Check that your API key hasn't been revoked in Settings
• Ensure your subscription is active (check Billing)

"Forbidden" Error

If you receive HTTP 403 (Forbidden):

• Your API key is valid, but your subscription tier doesn't include API access
• Upgrade to Professional or Agency if needed
• Contact support if you believe this is an error

"Not Found" Error

If you receive HTTP 404:

• The resource (project, prompt, etc.) doesn't exist
• The resource was deleted
• Check that the ID in your URL is correct

Rate Limit Exceeded

If you receive HTTP 429 with message "Rate limit exceeded":

• You've exceeded your tier's request limit
• Wait until the X-RateLimit-Reset timestamp (Unix time) before retrying
• Implement exponential backoff in your client
• Consider caching responses to reduce API calls
• Contact support to discuss upgrade options

Next Steps

• Read the API Reference for detailed endpoint documentation
• Explore example projects in the Getting Started guide
• Contact support at support@aibeam.io with questions