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 what it created: its jobs, its generated and uploaded media, and its projects, including the shots and renders inside them.
Every character belongs to one account. The account generates with it and sees every image and video of it, whoever made it. A key whose account owns no characters can’t bind any. It can edit or delete only what it created.
A key can be limited to certain workflows, and capped on how many jobs it runs at once. An empty workflow list allows every workflow.
A job can’t take another caller’s file as its input image, video or audio, unless the file is of one of its characters.

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.

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:
Terminal window
```
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.
Require keys. Set this in config.json. The API reads it on every request, so no restart is needed.
```
{ "security": { "require_api_key": true } }
```
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.

Your ComfyUI nodes

Keys protect Studio, not your ComfyUI nodes. ComfyUI has no authentication of its own: its security policy treats anyone who can reach its URL as trusted, and leaves securing a node exposed to the network to whoever exposed it. Studio doesn’t show a node’s address to a non-admin key, but anyone who reaches a node directly gets around every key. Keep your nodes off the public internet: a private network such as Tailscale does that, so only your own devices can reach them. To close it fully, let only the Studio host reach each node’s ComfyUI port, with a firewall or Tailscale’s access rules.

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 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] [--workflows a,b] [--max-concurrent N] [--key-file PATH]
python scripts/manage_agent_keys.py update <id> [--admin | --no-admin] [--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.

Character owners

A character belongs to the account that created it. An admin changes a character’s owner on its page in Studio, or with PATCH /api/characters/{id} and {"owner_id": "<account>"}. null leaves it unowned, which only admin keys can use.

To hand a key to an agent, see SKILL.md.