Manage keys for scripts and agents

Give a script, agent or service a key that reaches only what it needs, then narrow, expire, rotate or revoke it.

A key is the credential for a script, an agent that runs on its own or a service. It reaches only what you made it with: a photo import gets images and nothing else. A program people sign in to asks for your approval instead (Connect your agent).

You need the marfa CLI signed in with Full access, as the Quickstart sets it up. Access explains the maps and permissions a key holds.

Make a key

This key reads and writes images only:

Terminal
marfa keys create --label "Photo import" --source photo-import --type-permission core.file.image=write
marfa_k1_…
key 01a1fc38-bdf1-7519-a7dc-01f465cd925e (Photo import); the plaintext is shown once, keep it now
  core.file.image  Read and edit

Copy the key now

The key, which begins marfa_k1_, appears once. If you lose it, make a new one.

--label and --source are required. Name what the key holds. A key made with none of --type-permission, --permission or --edge-permission takes everything the sign-in that made it holds: with Full access, everything on your instance.

The key's default source stamps every item it creates, and it can't change later. One live key holds a source: a second key naming it is refused, as is a bookmark from the photo key. Fix a refused key or sign-in shows both.

Give a key a limited life

Add --expires-in 7d to keys create, or a time with --expires-at. Once the time passes, the key is gone: a request with it is refused 401 unauthorized, it leaves marfa keys list, and its source is free. Any key it makes ends no later than it does.

To give a live key more time, even one an app made, run marfa keys update <key-id> --expires-in 90d, or --no-expiry. It keeps its secret and reaches nothing more. From a key that ends itself, you can lengthen another only up to that end.

Narrow a key

marfa keys list shows each key's access, its last use and when it ends. Name a part to replace it and leave the rest. This makes the photo key read-only for 30 days:

Terminal
marfa keys update 01a1fc38-bdf1-7519-a7dc-01f465cd925e --type-permission core.file.image=read --expires-in 30d
01a1fc38-bdf1-7519-a7dc-01f465cd925e  Photo import  tier library  expires 2026-12-21T03:49:02.000Z
  core.file.image  Read only

A key an app made never reaches more than the app gave it: to give it more, make a new key. A key you made with Full access can also be widened, but never past what that sign-in holds.

Replace or revoke a key

Revoke a key that may have leaked before you replace it:

Terminal
marfa keys revoke 01a1fc38-bdf1-7519-a7dc-01f465cd925e
revoked key 01a1fc38-bdf1-7519-a7dc-01f465cd925e

Its next request is refused, and what it wrote stays. A key it made keeps working: find those with marfa audit --action key.create --query <key-id> and revoke them too.

For a planned change, make the new key first with the same access and its own --source, switch the script, check that marfa keys list shows the old key unused, then revoke it.

Give a key to a program

A key for a connector

A connector needs an owner's key, one that no change to an app's access ends, such as one made from the CLI with Full access. Each connector's Catalog page gives the command, and Connect a service walks through one.

A key for a folder watch

A watch that starts at login reads its key from the keychain. Where nobody signs in to unlock it, give it a key file that only you can read, kept outside every folder you sync.

marfa-watch.env
MARFA_API_URL=https://marfa.example.com
MARFA_API_KEY=marfa_k1_…
chmod 600 ~/.config/marfa-watch.env
marfa folders autostart on --key-file ~/.config/marfa-watch.env

Make the key reach only what the folders carry: each synced type as --type-permission (write for two-way sync), plus --type-permission system.folder=read and --edge-permission in-folder=write. Links and attachments need their own grants. system.folder=write is only for changing a folder's settings, such as holding it beneath a file.

A key for a script or an agent

Set MARFA_NO_KEYCHAIN=1, pass the key in MARFA_API_KEY from a secrets manager and the address in MARFA_API_URL. Work from an agent shows an agent's setup.

On this page