API keys#

API keys are the credentials your code uses to call the JSON2Video API. Every request must include the key in the x-api-key header. The dashboard at json2video.com/dashboard/apikeys is where you create, manage, and rotate them.

TODO: capture screenshot of the API keys panel showing the primary key and a list of secondary keys with their roles.

Two kinds of keys#

Primary API key#

• Every account has exactly one primary key.
• Auto-generated when you sign up.
• Has full account access (equivalent to the Manager role).
• Use this key only from trusted environments — your own server, your CI pipeline.

Secondary API keys (project keys)#

• You create them; you can have many.
• Each has a configurable role that limits what it can do.
• Each can have an optional expiration date.
• Use these for third-party integrations (Make.com, Zapier, n8n) and per-environment isolation.

Permission roles#

Secondary keys can be assigned one of three roles:

When you create a third-party integration, start with the minimum role (usually Render) and only escalate if the integration actually needs more. If a key is leaked, the blast radius is bounded by its role.

Creating a secondary key#

1. Open json2video.com/dashboard/apikeys.
2. Click Add new API key.
3. Give it a name (e.g. "Make.com — production").
4. Choose a role: Render, Editor, or Manager.
5. Optionally set an expiration date.
6. Click Save.

The new key appears once in a dialog — copy it immediately. After you close the dialog, the dashboard only shows a masked preview. If you lose a key, delete it and create a new one.

Using a key#

Send the key in the x-api-key header on every API request:

curl -X POST https://api.json2video.com/v2/movies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "resolution": "full-hd", "scenes": [ /* ... */ ] }'

Code samples for every SDK are in the Quickstart.

Rotating keys#

Rotating a secondary key#

1. Create a new secondary key with the same role.
2. Update the consuming service (Make.com, n8n, your code) with the new key.
3. Verify the service still works.
4. Delete the old key from the dashboard.

This pattern avoids downtime — both keys are valid during the transition window.

Resetting the primary key#

The primary key can be reset from the API keys panel:

1. Click Reset primary API key.
2. Confirm. A new primary key is generated and shown once.
3. Update every integration that uses the old primary key immediately — the old key stops working as soon as you reset.

Because resetting is disruptive, treat the primary key as an account-level credential and put real workloads on secondary keys.

Security best practices#

• Never commit keys to git. Use environment variables (JSON2VIDEO_API_KEY) and a .env file ignored by git.
• Never paste keys into public templates, Slack channels, or GitHub issues. Treat them like passwords.
• One key per environment. Production, staging, and development should each have their own key with the minimum role.
• One key per third-party integration. If Make.com is compromised, you should be able to revoke its key without touching anything else.
• Set expiration dates on keys for time-bound automations.
• Rotate keys on team changes. If someone with access to the dashboard leaves, rotate any keys they could have copied.

Revocation#

Delete a key from the dashboard to immediately revoke it. Any in-flight render started with that key continues — revocation only affects new requests.

See also#

• Getting started — Quickstart
• API endpoints reference
• Errors reference
• Make.com end-to-end