API Keys & Access

FlixML gives each caller its own API key: every AI agent, script and person. A caller sends its key on every request as Authorization: Bearer <key>.

What a key can see

• An admin key sees everything and can manage keys.
• Any other key sees only what it created: its jobs, its generated and uploaded media, and its projects, including the shots and renders inside them.
• A key can be limited to certain characters and workflows, and capped on how many jobs it runs at once. An empty list allows everything.
• A job can’t take another caller’s file as its input image, video or audio.

One known gap: a file already staged inside a ComfyUI node’s own input folder can still be named directly in workflow_params by a caller who knows its filename. Scoping covers what FlixML catalogs, not files placed into ComfyUI by other means.

FlixML stores a SHA-256 hash of each key, never the key itself, so a key is shown only once, when it’s created. If one is lost, replace it.

Secure a new install

A fresh install requires no key, so anyone who can reach the API or the UI has full access. Before you expose it beyond your own machine, create an admin key and turn keys on.

1. Create your admin key. In Studio, open Settings → API keys, click New key, tick Admin, and copy the key it shows you. On a machine without a browser, run this from the repo root with .env loaded instead:

   python scripts/manage_agent_keys.py create me "Me" --admin --key-file ~/.config/flixml/me.key

   --key-file writes the key to a file only you can read. Leave it off to print the key once.

2. Require keys. Set this in config.json. The API reads it on every request, so no restart is needed.

   { "security": { "require_api_key": true } }

3. Sign in. Reload Studio and paste your key into the sign-in prompt. The browser keeps it in an HttpOnly cookie.

Once keys are required, a request with no key gets a 401. A key that is unknown or revoked is rejected whether keys are required or not.

Manage keys

In Studio, open the account menu in the top-right corner and choose API keys, or go to Settings → API keys. Only admin keys can open it. From there you can:

• Create a key, choosing admin or a scope of characters, workflows and a job cap.
• Edit a key’s name and scope.
• Replace a key. The old one stops working immediately and the new one is shown once.
• Revoke a key, and enable it again later.
• Delete a key. What it made stays, visible to admin keys.

You can’t revoke, replace, delete or remove admin from the key you’re signed in with, so you can’t lock yourself out. Settings → Account shows which key the browser is using and signs it out.

The same operations are available from a terminal:

python scripts/manage_agent_keys.py list
python scripts/manage_agent_keys.py create <id> <name> [--admin] [--characters a,b] [--workflows a,b] [--max-concurrent N] [--key-file PATH]
python scripts/manage_agent_keys.py update <id> [--admin | --no-admin] [--characters a,b] [--workflows a,b] [--max-concurrent N]
python scripts/manage_agent_keys.py rotate <id> [--key-file PATH]
python scripts/manage_agent_keys.py revoke <id>
python scripts/manage_agent_keys.py enable <id>

Admin keys can also do it over HTTP with GET/POST /api/agents, PATCH/DELETE /api/agents/{id} and POST /api/agents/{id}/rotate.

Give an agent its key

Create a scoped key for the agent, then hand it over with an instruction like this:

Here is your FlixML API key: <key>. Send it on every request as Authorization: Bearer <key>, and read SKILL.md for how to use the API.

A 401 tells the agent its key is missing or revoked. A 403 or 404 on something you can see means its key isn’t scoped to it.