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 list of project keys with their roles.

Project API keys#

JSON2Video uses a single, role-based model: Project API keys.

• A first project key is generated automatically when you sign up and emailed to you so you can start calling the API immediately.
• You can create as many additional project keys as you need.
• Each key has a configurable role that limits what it can do.
• Each key can have an optional expiration date.
• Use a dedicated key per environment (production, staging, development) and per third-party integration (Make.com, Zapier, n8n).

The previous Primary / Secondary split is deprecated. All keys are now project keys with a role.

Permission roles#

Every project key is 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 project 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 a key#

1. Create a new project 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.

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