Authentication

Every API request authenticates with an mk_ API key. This page covers where keys come from, how to store one safely, what a key is bound to, and how to rotate or revoke it.

What a key looks like

mk_V1StGXR8Z5jdHi6BmyT0mRhLQmA3nUwx

A key is the literal string mk_ followed by 32 characters, 35 in total. Monofile stores only a SHA-256 hash of it plus the first eight characters as a display prefix, so you see the secret exactly once, at creation. Nobody, including Monofile support, can read it back. If you lose it, mint a new one.

Send it as a bearer token on every request:

{}

curl -s -X POST "https://www.monofile.ai/api/tools/get_key_info" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

Where keys come from

{"name": "Nova", "bio": "Research notes and reading summaries."}

echo $KEY | monofile login --with-key

Storing a key

Put the key in an environment variable and read it from there. Never paste it into source, a config file you commit, a notebook, a prompt or a chat message.

export MONOFILE_API_KEY="mk_..."

The CLI stores credentials per server in ~/.config/monofile/credentials.json. MONOFILE_API_KEY overrides whatever is on disk, so CI can inject the key as a secret.

If you save the key to a file yourself (the raw-API convention is ~/.monofile/credentials.json, a different file from the CLI's), restrict it:

chmod 600 ~/.monofile/credentials.json

What a key is bound to

A key fixes four things at creation:

A folder-scoped key behaves as though the workspace were just that folder:

• ls, tree, find and grep only see files inside it

• read only opens files inside it

• write and mkdir only create inside it

• anything addressed outside it returns OUT_OF_FOLDER_SCOPE

For the full shell, Monofile checks folder scope against what a command changed, not against the command text, so a script cannot write its way out.

Inspecting a key

When you do not know what a key can do, ask it:

{}

curl -s -X POST "https://www.monofile.ai/api/tools/get_key_info" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" -d '{}' | jq -r '.content[0].text' | jq .

{
  "workspace": { "type": "organization", "orgId": "org_abc123" },
  "folderScope": "/projects/alpha",
  "scopes": ["files:read", "files:write", "shares:read"],
  "userId": "user_abc123"
}

folderScope is null when the key can reach the whole workspace.

Rotating and revoking

A key's secret never changes, so there is no in-place rotation. Rotation is mint, switch, delete.

Revoking is immediate and permanent.

curl -s -X DELETE "https://www.monofile.ai/api/keys/<keyId>" \
  -H "Authorization: Bearer $MONOFILE_API_KEY"

GET /api/keys lists your keys as metadata: id, name, prefix, scopes, workspace, folder, expiry and last use. The response contains no plaintext keys. A key may delete any of its owner's keys, including itself, so the session that discovers a compromise can revoke the credential at once.

Next steps