# Manage keys for scripts and agents (/use/manage-keys)

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](/connect-your-agent#approve-what-it-may-reach)).

You need the `marfa` CLI signed in with **Full access**, as the [Quickstart](/quickstart) sets it up. [Access](/build/access) explains the maps and permissions a key holds.

## Make a key [#make-a-key]

This key reads and writes images only:

```bash
marfa keys create --label "Photo import" --source photo-import --type-permission core.file.image=write
```

Output:

```text
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](/run/troubleshooting/credentials-and-access#403-type_not_permitted) shows both.

## Give a key a limited life [#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 [#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:

```bash
marfa keys update 01a1fc38-bdf1-7519-a7dc-01f465cd925e --type-permission core.file.image=read --expires-in 30d
```

Output:

```text
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 [#replace-or-revoke-a-key]

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

```bash
marfa keys revoke 01a1fc38-bdf1-7519-a7dc-01f465cd925e
```

Output:

```text
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 [#give-a-key-to-a-program]

### A key for a connector [#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](/catalog/connectors) gives the command, and [Connect a service](/use/connect-a-service#make-its-key) walks through one.

### A key for a folder watch [#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.

```bash title="marfa-watch.env"
MARFA_API_URL=https://marfa.example.com
MARFA_API_KEY=marfa_k1_…
```

```bash
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](/use/sync-a-folder#hold-one-project).

### A key for a script or an agent [#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](/use/from-an-agent#an-agent-that-runs-on-its-own) shows an agent's setup.
