API Authentication

All GigaReels API requests require authentication using API keys. This guide covers authentication methods, security best practices, and troubleshooting.

Authentication Methods

Bearer Token

Standard HTTP Bearer authentication (recommended)

CLI Authentication

Automatic credential management for development

Bearer Token Authentication

Request Format

Include your API key in the Authorization header:

curl -X POST "https://gigareels.com/api/render" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "educational-brainrot",
    "prompt": "Explain quantum physics",
    "characterPack": "rick-and-morty",
    "backgroundVideoPack": "minecraft-parkour"
  }'

SDK Implementation

The SDK handles authentication automatically:

import { GigaReels } from "@gigareels/sdk";

// Manual API key
const client = new GigaReels({
	apiKey: "your-api-key-here",
});

// Environment variable
const client = new GigaReels({
	apiKey: process.env.GIGAREELS_API_KEY,
});

// CLI credentials (automatic)
const client = new GigaReels(); // Uses stored credentials

API Key Management

Getting Your API Key

Log in to your GigaReels Dashboard
Navigate to Settings → API Keys
Click Generate New API Key
Copy and securely store your API key

Security: API keys provide full access to your account. Never share them publicly or commit them to version control.

Key Properties

string

required

Your unique API key from the dashboard

string

Always starts with giga_ followed by 32 alphanumeric characters

string

Full access to all API endpoints and features

string

API keys do not expire but can be revoked from the dashboard

CLI Authentication

# Authenticate via browser
npx @gigareels/sdk login

# For local development
npx @gigareels/sdk login --local

The CLI authentication flow:

Browser Authentication

CLI opens your browser to the GigaReels authentication page

Account Verification

API Key Generation

System automatically generates an API key for CLI use

Local Storage

Credentials are stored in ~/.gigareels/credentials.json

Checking Authentication Status

import { GigaReels } from "@gigareels/sdk";

// Check if CLI authentication exists
const isLoggedIn = await GigaReels.isLoggedIn();
console.log("Authenticated:", isLoggedIn);

Logout

# Clear stored credentials
npx @gigareels/sdk logout

Authentication Errors

Common Error Responses

401 Unauthorized

Cause: Invalid or missing API key

{
  "error": "Invalid API key"
}

Solutions:

Verify your API key is correct
Check the Authorization header format
Regenerate your API key if compromised

403 Forbidden

Cause: Valid API key but insufficient permissions

{
  "error": "Insufficient permissions for this operation"
}

Solutions:

Check your account subscription level
Verify the endpoint requires the permissions you have
Contact support if you believe this is an error

429 Too Many Requests

Cause: Rate limit exceeded

{
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

Solutions:

Implement exponential backoff in your requests
Check your rate limits in the dashboard
Consider upgrading your plan for higher limits

Security Best Practices

API Key Security

🔒 Storage

Store in environment variables - Use secure secret management systems - Never commit to version control - Rotate keys regularly

🌐 Network Security

Always use HTTPS - Validate SSL certificates - Use proper CORS settings - Implement request timeouts

🚨 Monitoring

Monitor for unusual usage patterns - Log authentication failures - Set up alerts for suspicious activity - Track API key usage in dashboard

🔄 Rotation

Rotate keys every 90 days - Generate new keys before travel - Revoke unused or compromised keys - Use separate keys per environment

Environment Variables

Set up secure environment variable management:

Development (.env)
Production (Docker)

# .env (never commit this file)
GIGAREELS_API_KEY=giga_your_development_key_here
GIGAREELS_BASE_URL=https://gigareels.com

# Dockerfile ENV # docker run command docker run -e

GIGAREELS_API_KEY=giga_your_prod_key_here myapp ```
</Tab>

<Tab title="Production (Cloud)">
```bash
# AWS Lambda
aws lambda update-function-configuration \
  --function-name my-function \
  --environment Variables='{GIGAREELS_API_KEY=giga_your_key_here}'

# Vercel
vercel env add GIGAREELS_API_KEY

# Heroku
heroku config:set GIGAREELS_API_KEY=giga_your_key_here

Request Security

Implement secure request patterns:

import { GigaReels } from "@gigareels/sdk";

class SecureGigaReelsClient {
	constructor() {
		// Validate API key format
		const apiKey = process.env.GIGAREELS_API_KEY;
		if (!apiKey || !apiKey.startsWith("giga_")) {
			throw new Error("Invalid API key format");
		}

		this.client = new GigaReels({
			apiKey,
			baseUrl: process.env.GIGAREELS_BASE_URL || "https://gigareels.com",
		});
	}

	async generateVideo(params) {
		try {
			// Add request timeout
			const timeout = new Promise((_, reject) =>
				setTimeout(() => reject(new Error("Request timeout")), 30000)
			);

			const request = this.client.templates.brainrot.educational(params);

			return await Promise.race([request, timeout]);
		} catch (error) {
			// Log error without exposing sensitive data
			console.error("Video generation failed:", {
				error: error.message,
				timestamp: new Date().toISOString(),
				// Don't log the full request or API key
			});
			throw error;
		}
	}
}

Rate Limits

Default Limits

Endpoint	Requests per Minute	Requests per Hour	Requests per Day
`/api/render`	10	100	1000
`/api/render/status/*`	60	1000	10000
`/api/social-media/*`	30	300	3000

Rate Limit Headers

API responses include rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1640995200

Handling Rate Limits

async function makeRequestWithRetry(requestFn, maxRetries = 3) {
	for (let attempt = 1; attempt <= maxRetries; attempt++) {
		try {
			return await requestFn();
		} catch (error) {
			if (error.message.includes("429") && attempt < maxRetries) {
				// Exponential backoff
				const delay = Math.pow(2, attempt) * 1000;
				console.log(`Rate limited. Retrying in ${delay}ms...`);
				await new Promise(resolve => setTimeout(resolve, delay));
				continue;
			}
			throw error;
		}
	}
}

// Usage
const result = await makeRequestWithRetry(() => client.templates.brainrot.educational(params));

Testing Authentication

Test Script

import { GigaReels } from "@gigareels/sdk";

async function testAuthentication() {
	try {
		const client = new GigaReels({
			apiKey: process.env.GIGAREELS_API_KEY,
		});

		// Test with a simple status check
		const task = await client.getTaskStatus("test_task_id");
		console.log("✅ Authentication successful");
	} catch (error) {
		if (error.message.includes("401")) {
			console.log("❌ Invalid API key");
		} else if (error.message.includes("404")) {
			console.log("✅ Authentication successful (task not found is expected)");
		} else {
			console.log("❌ Unexpected error:", error.message);
		}
	}
}

testAuthentication();

CLI Testing

# Test CLI authentication
npx @gigareels/sdk login

# Verify stored credentials
cat ~/.gigareels/credentials.json

Migration Guide

From v1 to v2 Authentication

If you’re upgrading from an older version:

Old Format
New Format

// ❌ Old authentication method
const client = new GigaReels({
  token: "your-token-here"
});

// ✅ New authentication method
const client = new GigaReels({
  apiKey: "giga_your_api_key_here"
});

Credential Migration

# Check if you need to migrate
npx @gigareels/sdk logout
npx @gigareels/sdk login

# This will create new v2 format credentials

Troubleshooting

API Key Not Working

Verify the key format starts with giga_
Check for extra spaces or characters
Ensure you’re using the correct environment
Try generating a new API key

CLI Authentication Failed

Clear existing credentials: npx @gigareels/sdk logout 2. Try logging in again: npx @gigareels/sdk login 3. Check your internet connection 4. Try using --local flag for development

Network Errors

Verify you can reach https://gigareels.com
Check firewall and proxy settings
Ensure SSL certificates are valid
Try a different network connection

Next Steps

Get Your API Key

Generate an API key from the GigaReels dashboard

Set Up Environment

Configure environment variables for secure key storage

Test Authentication

Verify your setup with a simple API call

Implement Security

Add proper error handling and security measures

Ready to Make API Calls?

Continue to the Render API Reference to start generating content.

​API Authentication

​Authentication Methods

Bearer Token

CLI Authentication

​Bearer Token Authentication

​Request Format

​SDK Implementation

​API Key Management

​Getting Your API Key

​Key Properties

​CLI Authentication

​Login Process

​Checking Authentication Status

​Logout

​Authentication Errors

​Common Error Responses

​Security Best Practices

​API Key Security

🔒 Storage

🌐 Network Security

🚨 Monitoring

🔄 Rotation

​Environment Variables

​Request Security

​Rate Limits

​Default Limits

​Rate Limit Headers

​Handling Rate Limits

​Testing Authentication

​Test Script

​CLI Testing

​Migration Guide

​From v1 to v2 Authentication

​Credential Migration

​Troubleshooting

​Next Steps

Ready to Make API Calls?

API Authentication

Authentication Methods

Bearer Token Authentication

Request Format

SDK Implementation

API Key Management

Getting Your API Key

Key Properties

CLI Authentication

Login Process

Checking Authentication Status

Logout

Authentication Errors

Common Error Responses

Security Best Practices

API Key Security

Environment Variables

Request Security

Rate Limits

Default Limits

Rate Limit Headers

Handling Rate Limits

Testing Authentication

Test Script

CLI Testing

Migration Guide

From v1 to v2 Authentication

Credential Migration

Troubleshooting

Next Steps