​
Overview

The Bluma API uses API keys for authentication. All requests must include a valid API key in the Authorization header using the Bearer authentication scheme.

​
API Key Format

Bluma API keys follow this format:
  • Test keys: bluma_test_xxxxxxxxxxxx
  • Production keys: bluma_live_xxxxxxxxxxxx
Test keys generate watermarked videos and don’t consume credits. Production keys generate full-quality videos and charge credits.

​
Authentication Header

Include your API key in every request: 
Authorization: Bearer bluma_live_your_api_key_here

​
Example Request

curl https://api.getbluma.com/api/v1/templates \
  -H "Authorization: Bearer bluma_live_abc123xyz789"

​
Creating API Keys

​
Via Dashboard

  1. Log in to your Bluma dashboard
  2. Navigate to API Keys
  3. Click Create API Key
  4. Choose a name and environment (test or production)
  5. Set rate limits based on your tier
  6. Save the key securely (shown only once!)

​
Via API

You can also create API keys programmatically (requires an existing key): 
curl -X POST https://api.getbluma.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server Key",
    "environment": "production",
    "rate_limit_per_hour": 1000
  }'

{
  "api_key": "bluma_live_newkey123xyz789",
  "id": "key_abc123",
  "name": "Production Server Key",
  "environment": "production",
  "prefix": "bluma_live_newkey123",
  "scopes": ["videos:create", "videos:read", "templates:list"],
  "rate_limit_per_hour": 1000,
  "created_at": "2025-11-03T10:30:00Z",
  "warning": "Save this API key now. You will not be able to see it again!"
}

​
Managing API Keys

​
Listing Your Keys

View all your API keys (without exposing the full key): 
curl https://api.getbluma.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

​
Rotating Keys

For zero-downtime key rotation, use the rotate endpoint: 
curl -X POST https://api.getbluma.com/api/v1/api-keys/key_abc123/rotate \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
This creates a new key and schedules the old one for expiration in 30 days, giving you time to update your applications.

​
Revoking Keys

Immediately revoke a compromised key: 
curl -X DELETE https://api.getbluma.com/api/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
Revoking a key immediately stops all requests using that key. Make sure you have a replacement key ready.

​
Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code. Use environment variables:
export BLUMA_API_KEY=bluma_live_xxx

Restrict by Environment

Use test keys for development and staging. Only use production keys in production.

Rotate Regularly

Rotate your API keys every 90 days for enhanced security.

Monitor Usage

Regularly check your usage dashboard for unusual activity.

​
API Scopes

API keys have the following scopes by default:
ScopeDescription
videos:createGenerate new videos
videos:readView video status and details
videos:downloadDownload generated videos
templates:listBrowse available templates
templates:readView template details
credits:readCheck credit balance and history
webhooks:manageCreate and manage webhooks
usage:readView usage analytics
Custom scopes are available for Enterprise plans. Contact support@getbluma.com for more information.

​
Rate Limits

Each API key has a rate limit based on your subscription tier:
TierRequests/HourVideos/Month
Free10010
Starter1,000100
Pro5,000500
Enterprise50,0003,000
Rate limit headers are included in every response: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1699123456
See Rate Limits for more details.

​
Error Handling

​
401 Unauthorized

Cause: Missing or invalid API key 
{
  "error": {
    "type": "authentication_error",
    "title": "Authentication Required",
    "status": 401,
    "detail": "Valid API key required. Include it in the Authorization header.",
    "links": {
      "docs": "https://docs.getbluma.com/authentication"
    }
  }
}
Solution: Check that your API key is correct and properly formatted in the Authorization header.

​
403 Forbidden

Cause: API key lacks required permissions 
{
  "error": {
    "type": "permission_denied",
    "title": "Permission Denied",
    "status": 403,
    "detail": "This API key does not have permission to access this resource.",
    "metadata": {
      "required_scope": "videos:create",
      "available_scopes": ["videos:read", "templates:list"]
    }
  }
}
Solution: Use an API key with the required scopes or create a new key with appropriate permissions.

​
Testing Authentication

Verify your API key is working: 
curl https://api.getbluma.com/api/v1/credits/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
A successful response confirms your key is valid: 
{
  "credits": 100,
  "tier": "starter",
  "monthly_allowance": 100
}

​
Next Steps

Generate Your First Video

Start creating videos with your API key

Set Up Webhooks

Configure webhook notifications

Monitor Usage

Track API usage and performance

Error Handling

Learn how to handle API errors