API keys

Update an API key

Updates a key and returns it. Each supplied field replaces its value; omitted fields stay unchanged. Requires keys.mint, keys.manage, or local authority.

PATCH
/keys/{id}

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Path parameters

id*string

The ID of the key.

Header parameters

X-Marfa-Instance-Id?string

The ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

application/json
  1. body
label?string

A name for the key, to tell it apart from your other keys.

Length1 <= length
default_tier?string

The tier an item this key creates goes to when the write names none.

Value in"library""feed"
sources?array<>

Sources the key may also write under, besides its own source. Several keys may claim one source, so their writes share natural keys. You can grant your own source and your claims, or with keys.manage any source; the local command can grant any.

Itemsitems <= 1000
type_permissions?

Item types the key may read or write, by type ID or a wildcard such as core.* or *. none denies a type a wildcard covers.

extension_permissions?

Extension namespaces the key may read or write, by namespace or *.

edge_permissions?

Edge types the key may read or write, by edge type, a namespace wildcard such as user.*, or *.

metadata_permissions?

Registrations the key may make: types to register types and edge_types to register edge types, at write. * covers both.

profile_permissions?

Profile access by name, username, email, avatar, or *. write implies read. write on a field changes it, and only username at write changes the username. * reads every field and at write changes every field but the username.

permissions?array<>

The permissions the key holds, such as audit.read.

enforcement_override?|

Replaces the key's enforcement levers whole. null clears them.

expires_at?|

Replaces when the key stops working, as an ISO 8601 date and time in the future. null clears it. Leave it out to keep it. It can't be later than the key's current one for a key an app made, with narrow_only, or without keys.mint. It also can't be later than your own key's expires_at, unless you hold keys.manage and it isn't later than the key's current one.

source?string

Can't change. To give a key another source, create a new key and revoke this one.

narrow_only?boolean

true to refuse the update if it would give the key more: a permission, map entry or claimed source it doesn't hold, a later expires_at or none, or an enforcement_override other than its own. Defaults to false.

Response body

About errors

Returns the updated key.

application/json
  1. response

An API key, without its plaintext: what it may reach and when it was used.

id*string

Unique identifier for the key.

label*string

A name for the key, to tell it apart from your other keys.

source*string

The key's own source, stamped on the items it writes unless a write names a source it claims. No other key that hasn't been revoked or expired has it as its own, and it can't change.

sources*array<string>

Sources the key may also write under, besides its own source. Several keys may claim one source, so their writes share natural keys. Empty if the key claims none.

permissions*array<>

The permissions the key holds, such as audit.read. Empty if it holds none.

oauth_client_id?string

The app origin client ID, inherited by every descendant key but an owner's key (owner_key). Absent when no app is in the key's origin, and on an owner's key.

default_tier*string

The tier an item this key creates goes to when the write names none.

Value in"library""feed"
type_permissions*

Item types the key may read or write, by type ID or a wildcard such as core.* or *. none denies a type a wildcard covers.

extension_permissions*

Extension namespaces the key may read or write, by namespace or *.

edge_permissions*

Edge types the key may read or write, by edge type, a namespace wildcard such as user.*, or *.

metadata_permissions*

Registrations the key may make: types to register types and edge_types to register edge types, at write. * covers both.

profile_permissions*

Stored profile levels by field. Only the username entry permits writing the username; a wildcard reads it.

enforcement_override?

The key's own enforcement levers. Absent if the key sets none, so it follows the instance's.

created_at*string

When the key was created, in UTC.

expires_at*|

When the key stops working, in UTC, or null if it doesn't expire.

last_used_at*|

When the key's use was last recorded, in UTC, or null if none is recorded. Marfa records usage asynchronously at most once an hour; a busy or unavailable store can delay or drop a record.

  • missing_required_field: a lever in enforcement_override lacks types or sources.
  • validation_error: id isn't a valid key ID, the body carries source, or a field is invalid, such as an expires_at that isn't a time or isn't in the future, or a claimed source that starts with oauth:.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: you hold neither keys.mint nor keys.manage, or only keys.manage and it widens or lengthens the key; it gives more than you hold or an expires_at later than yours, unless keys.manage narrows it; it widens or lengthens an app's key, or any key with narrow_only, which also refuses a changed enforcement_override; or it names enforcement_override without config.manage.
application/json
  1. response

An error response.

error*

What went wrong.

  • key_not_found: no key you could have created has this ID, or the key is revoked or past its expires_at.
application/json
  1. response

An error response.

error*

What went wrong.

request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.

application/json
  1. response

An error response.

error*

What went wrong.

instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.

application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X PATCH 'http://localhost:8600/keys/string' \  -H 'Content-Type: application/json' \  -d '{}'
About errors
{  "id": "01a10126-1e03-79a5-ba6f-f711fc6f0e95",  "label": "reporting dashboard",  "source": "reporting",  "sources": [],  "permissions": [    "instance.read"  ],  "default_tier": "library",  "type_permissions": {    "acme.deal": "read"  },  "extension_permissions": {},  "edge_permissions": {},  "metadata_permissions": {},  "profile_permissions": {},  "created_at": "2026-10-03T10:08:20.575Z",  "expires_at": null,  "last_used_at": null}