Access

How a key or an app is limited to the data and operations it needs, and how each one gets its access.

Each credential reaches only what it was given. A photo app can write images, read the rest, and see nothing of the owner's messages.

Credentials

Two kinds of credential call the API, each sent as Authorization: Bearer <credential>:

CredentialLooks likeHolds
A keymarfa_k1_…What it was made with
An app's access tokenmarfa_at_…What the owner approved for the app

The owner's browser session is neither. It counts only on the sign-in and approval pages: it never reads an item or changes a setting, so a page that rides on the owner's cookie reaches nothing. What the owner's browser reaches lists those pages.

The server's own machine has one more authority, the private socket, which the CLI uses to claim an instance and recover the owner's password.

What a credential reaches

A credential's maps say which data it reads and writes, and its permissions which other operations it may use.

The photo app's key, made from the CLI:

Terminal
marfa keys create --label "Photo app" --source photo-app \
  --type-permission core.file.image=write \
  --type-permission 'core.*=read' \
  --type-permission core.message=none \
  --edge-permission about=write
marfa_k1_…
key 01a1f1a2-a184-736a-b69c-1e18d5770812 (Photo app); the plaintext is shown once, keep it now
  core.file.image  Read and edit
  Built-in types   Read only
  core.message     No access
  edge.about       Read and edit

A map names things at a level, read or write, and write includes reading. Anything a map doesn't name is out of reach. A credential has five maps: types of item, edge types, extension namespaces, metadata (registering types and edge types) and the owner's profile.

The type map matters most, and only it takes a third level, none, which shuts out a type its wildcard covers. The Catalog's Permissions page lists each map's field, flag and entries, and the rules that apply to each.

What a refusal reveals

An item of a type the credential can't read answers 404 item_not_found, as an item that doesn't exist does, so a refusal reveals nothing. So do its edges, and a blob only such items name. An item the credential can read but not write is refused with 403 type_not_permitted.

So the photo app's key reads a message as missing, reads a note, and is refused when it changes the note.

The key may read and write this type, so both operations go through.

The key may read and write this type, so both operations go through.

The key holds
A type map
core.file.image
write
core.event
None
core.media.book
None
Marfa answers
By its id, for an item of core.file.image
Read it
200 allowed
Change it
200 allowed

Permissions

A permission opens a group of operations, such as making keys. It opens no items: a key with every permission and no type map reads nothing. The Catalog's Permissions page lists all fourteen.

How an app gets access

Signing in with OAuth is how an app reaches Marfa. The instance is its own authorization server: its address is the issuer, the endpoints live under /oauth, and /.well-known/oauth-authorization-server lists them. Every app is a public client, holding no secret, and proves itself with PKCE. An AI agent connecting to the MCP server signs in the same way.

  1. The app registers itself and names the scopes it wants. One that names none asks to read and write every type outside system and marfa, and the edges between items, with offline_access.
  2. It sends the owner to the approval page, where the owner chooses Full access, or Choose access to give it less.
  3. The app exchanges the code for an access token and a refresh token.

The app then holds a grant, exactly what the owner approved, and writes under the source oauth:<client_id>. A grant outlives the browser session that approved it. The owner can narrow it, which revokes each key the app made that holds more, and it lasts until the owner disconnects the app or the app goes unused for grant_inactivity_days, a year by default.

A web page connects the same way. Once the owner approves it, its address may call the instance from a browser, and cors_origins adds others. No answer allows credentials, so a page reaches only what its token holds.

Authenticate and Connect a web page show the app's side, and Manage apps the owner's.

How a key gets access

A key suits a script, your own agent or a connector. The owner makes one from the CLI, and any key or app holding keys.mint can make another. A made key holds only the maps and permissions its maker holds, and its expiry is never later than its maker's. A key an app makes stays within the app's grant, can name no extension namespace, and carries the app's oauth_client_id. Manage keys shows how.

The rules behind this page are in the keys and sign-in and authentication chapters of the contract.

On this page