Authentication - Bluma API

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

Log in to your Bluma dashboard
Navigate to API Keys
Click Create API Key
Choose a name and environment (test or production)
Set rate limits based on your tier
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
  }'

View Response

{
  "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:

Scope	Description
`videos:create`	Generate new videos
`videos:read`	View video status and details
`videos:download`	Download generated videos
`templates:list`	Browse available templates
`templates:read`	View template details
`credits:read`	Check credit balance and history
`webhooks:manage`	Create and manage webhooks
`usage:read`	View 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:

Tier	Requests/Hour	Videos/Month
Free	100	10
Starter	1,000	100
Pro	5,000	500
Enterprise	50,000	3,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

​Overview

​API Key Format

​Authentication Header

​Example Request

​Creating API Keys

​Via Dashboard

​Via API

​Managing API Keys

​Listing Your Keys

​Rotating Keys

​Revoking Keys

​Security Best Practices

Use Environment Variables

Restrict by Environment

Rotate Regularly

Monitor Usage

​API Scopes

​Rate Limits

​Error Handling

​401 Unauthorized

​403 Forbidden

​Testing Authentication

​Next Steps

Generate Your First Video

Set Up Webhooks

Monitor Usage

Error Handling

Overview

API Key Format

Authentication Header

Example Request

Creating API Keys

Via Dashboard

Via API

Managing API Keys

Listing Your Keys

Rotating Keys

Revoking Keys

Security Best Practices

API Scopes

Rate Limits

Error Handling

401 Unauthorized

403 Forbidden

Testing Authentication

Next Steps