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.
Bluma API keys follow this format:
Test keys: bluma_test_xxxxxxxxxxxxProduction keys: bluma_live_xxxxxxxxxxxx
Test keys generate watermarked videos and don’t consume credits. Production keys generate full-quality videos and charge credits.
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 }'
{ "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.
API Scopes API keys have the following scopes by default:
Scope Description 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:
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