Authentication

All API requests require an API key. Keys are scoped with granular permissions to limit access to specific resources and operations.

Creating API Keys

API keys are created in your dashboard settings. Studio tier or above is required for API access.

Important: API keys are shown only once during creation. Save them immediately — they cannot be retrieved later.

Using the Dashboard

Navigate to Settings → API Keys
Click "Create API Key"
Give it a name (e.g., "Production", "CI/CD", "Test")
Choose a scope preset or select individual scopes
Click "Create" and copy the key immediately

Programmatically (Session Required)

You can create API keys programmatically if you have a valid session cookie. This is useful for automated provisioning or CI/CD workflows.

curl

curl -X POST https://app.sigfigsstudio.com/api/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: [your session cookie]" \
  -d '{
    "name": "Production API Key",
    "scopes": "render-batch"
  }'

Response

{
  "success": true,
  "key": "sf_live_a1b2c3d4e5f6789abcdef123456",
  "apiKey": {
    "id": "clx123...",
    "name": "Production API Key",
    "keyPrefix": "sf_live_a1b2c3d4",
    "scopes": "videos:create,videos:create:batch,videos:read"
  },
  "message": "Save this API key — it won't be shown again."
}

Using API Keys

Include your API key in every request using the X-API-Key header or as a Bearer token.

Using X-API-Key Header (Recommended)

curl

curl -H "X-API-Key: sf_live_YOUR_KEY_HERE" \
  https://app.sigfigsstudio.com/api/render

Using Bearer Token

curl

curl -H "Authorization: Bearer sf_live_YOUR_KEY_HERE" \
  https://app.sigfigsstudio.com/api/render

In Python

Python

import requests
import os

API_KEY = os.environ["SIGFIGS_API_KEY"]

response = requests.get(
    "https://app.sigfigsstudio.com/api/render/JOB_ID",
    headers={"X-API-Key": API_KEY}
)

In Node.js

JavaScript

const API_KEY = process.env.SIGFIGS_API_KEY;

const response = await fetch(
  "https://app.sigfigsstudio.com/api/render/JOB_ID",
  { headers: { "X-API-Key": API_KEY } }
);

API Key Scopes

Scopes limit what an API key can do. Choose the minimal set of scopes needed for your integration to reduce security risk.

Scope	Description	Required For
`videos:create`	Create single render jobs	`POST /api/render`
`videos:create:batch`	Create batch render jobs (CSV)	`POST /api/render/batch`
`videos:read`	Poll render status, get video URLs	`GET /api/render/:id`
`videos:delete`	Delete rendered videos	`DELETE /api/render/:id`
`templates:read`	List templates, view data schemas	`GET /api/templates`
`templates:write`	Create, update, fork, and delete templates
`projects:read`	List and view saved projects	`GET /api/projects`
`projects:write`	Create, update, delete projects	`POST/PATCH/DELETE /api/projects`
`billing:read`	View credit balance and usage history	`GET /api/billing`
`webhooks:manage`	Create and update webhook endpoints	`GET/POST/DELETE /api/webhooks`
`keys:manage`	Create and revoke API keys	`GET/POST/DELETE /api/keys`

Scope Presets

For convenience, we offer preset combinations of scopes for common use cases:

`render-only`

Single renders and status polling. Most minimal integration.

Scopes: videos:create, videos:read

`render-batch`

Batch rendering from CSV. Recommended for campaigns.

Scopes: videos:create, videos:create:batch, videos:read

`full-access`

All video and project operations (no billing or key management).

Scopes: videos:*, projects:*, templates:read

`read-only`

View-only access for monitoring or analytics integrations.

Scopes: videos:read, projects:read, billing:read

`admin`

Everything including API key and webhook management.

Scopes: * (all scopes)

Rate Limits

Rate limits are applied per API key. Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Endpoint	Limit	Burst
`POST /api/render`	30 requests/min	10
`POST /api/render/batch`	5 requests/min	2
`GET /api/render/:id`	120 requests/min	30
`GET/POST /api/keys`	30 requests/min	10
`All other endpoints`	60 requests/min	15

Rate Limit Headers

All responses include rate limit headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1710885600

# On 429 error:
Retry-After: 45

Tip: Implement exponential backoff when you receive a 429 response. Check Retry-After header for the recommended wait time.

Security Best Practices

Never Commit Keys to Version Control

Use environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault, etc.). Add .env to .gitignore.

.gitignore

.env
.env.local
*.key

Use Minimal Scopes

Grant only the permissions your integration needs. For example, if you only render videos, use render-only instead of admin.

Rotate Keys Regularly

Create a new key, update your integration, then revoke the old key. Recommended rotation schedule: every 90 days for production keys.

Create new API key with same scopes
Update your application environment variables
Test the new key in staging
Deploy to production
Revoke old key via dashboard or DELETE /api/keys/:id

Use Separate Keys Per Environment

Create different API keys for development, staging, and production. This isolates environments and makes it easier to revoke a compromised key without affecting others.

Monitor Key Usage

Track API key usage in your dashboard. Unusual activity (sudden spike in requests, requests from unexpected IPs) may indicate a compromised key.

Server-Side Only

Never expose API keys in client-side code (JavaScript, mobile apps). Always make API calls from your backend server.

API Key Rotation Example

Here's a Python script for zero-downtime key rotation:

rotate_key.py

import requests
import os
import time

SESSION_COOKIE = os.environ["SESSION_COOKIE"]
OLD_KEY = os.environ["SIGFIGS_API_KEY"]
BASE_URL = "https://app.sigfigsstudio.com/api"

# 1. Create new key
response = requests.post(
    f"{BASE_URL}/keys",
    headers={
        "Content-Type": "application/json",
        "Cookie": SESSION_COOKIE
    },
    json={
        "name": f"Production Key {int(time.time())}",
        "scopes": "render-batch"
    }
)

new_key = response.json()["key"]
print(f"✓ New key created: {new_key[:20]}...")

# 2. Test new key
test_response = requests.get(
    f"{BASE_URL}/billing",
    headers={"X-API-Key": new_key}
)

if test_response.status_code == 200:
    print("✓ New key validated")
else:
    print("✗ New key validation failed")
    exit(1)

# 3. Update environment (manual step)
print(f"\n→ Update SIGFIGS_API_KEY in your environment to: {new_key}")
print("→ Deploy to production")
print("→ Run this script again with --revoke-old to finish rotation")

# 4. Revoke old key (after deployment)
if "--revoke-old" in sys.argv:
    # Get old key ID
    keys_response = requests.get(
        f"{BASE_URL}/keys",
        headers={"Cookie": SESSION_COOKIE}
    )
    
    old_key_prefix = OLD_KEY[:16]
    old_key_id = next(
        k["id"] for k in keys_response.json()["keys"] 
        if k["keyPrefix"] == old_key_prefix
    )
    
    # Revoke
    requests.delete(
        f"{BASE_URL}/keys/{old_key_id}",
        headers={"Cookie": SESSION_COOKIE}
    )
    
    print(f"✓ Old key revoked: {old_key_prefix}...")

Ready to integrate securely?

Create an API key with minimal required scopes and start building.

Create API Key Quickstart Guide