Authentication

Every request to the API, the CLI and the MCP server carries an API key. The same key works on all three.

#Key format

A key is ff_ followed by 64 hex characters. FusedFrames stores only a hash of it, so the full key is shown once, when it is created. If you lose a key, regenerate it or create a new one.

Every key is read-only by design. It lets other tools read your data, not change it.

#Creating a key in the dashboard

Open the API keys page in the dashboard and select Create key. The page appears for roles with the dashboard:api-keys permission. You set four things:

• Name. A name like Production server, unique in the workspace.
• Document libraries. The libraries the key can read. Every key is scoped to the libraries you pick here.
• Expires. 30 days, 90 days, 1 year (the default) or Never.
• Allow access to recording details. Off by default. Turn it on and the key can read the source recordings behind a document; without it that endpoint answers 403. As the dialog warns, recording details include typed text and clicks.

The new key appears once, in the API key created dialog. Copy it before you close the window; you cannot see it again.

#Creating a key in the desktop app

The Individual plan has no dashboard, so you create your key in the desktop app instead. A key created there is tied to the device that made it:

• It sees only that device's libraries.
• If the device is archived or deleted, the key stops working and every request returns api_key_device_removed.

Keys created in the desktop app never appear in the dashboard, and dashboard keys never appear in the desktop app.

#Using a key

Send the key as a bearer token in the Authorization header on every request:

Authorization: Bearer ff_your_key

#What a key can see

A key sees only the document libraries it was scoped to. A dashboard key can also never see a library its creator cannot see, so one member's key can never open another member's private libraries.

#Key lifecycle

• Regenerate gives a key a new secret, shown once. The old secret stops working straight away.
• Edit renames a key, changes its libraries or expiry and toggles recording-details access.
• Delete removes the key. Any tool using it stops working, and you cannot undo it.
• When a key passes its expiry date, requests fail with api_key_expired. Regenerate it or create a new one.

Every request a key makes shows in the request log, in the dashboard and the desktop app.

#Keeping keys safe

• Store the key in an environment variable, not in code.
• Never pass it as a command-line argument; arguments end up in shell history and process lists.
• Scope each key to the libraries it needs, and leave recording details off unless you need them.
• If a key leaks, regenerate or delete it.

The CLI takes your key on stdin or from the FUSEDFRAMES_API_KEY environment variable, never as an argument.