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.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
id*stringThe ID of the key.
X-Marfa-Instance-Id?stringThe 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.
^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$application/json- body
label?stringA name for the key, to tell it apart from your other keys.
1 <= lengthdefault_tier?stringThe tier an item this key creates goes to when the write names none.
"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.
items <= 1000type_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?stringCan't change. To give a key another source, create a new key and revoke this one.
narrow_only?booleantrue 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.
Returns the updated key.
application/json- response
An API key, without its plaintext: what it may reach and when it was used.
id*stringUnique identifier for the key.
label*stringA name for the key, to tell it apart from your other keys.
source*stringThe 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?stringThe 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*stringThe tier an item this key creates goes to when the write names none.
"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*stringWhen 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 inenforcement_overridelackstypesorsources.validation_error:idisn't a valid key ID, the body carriessource, or a field is invalid, such as anexpires_atthat isn't a time or isn't in the future, or a claimed source that starts withoauth:.
application/json- 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- response
An error response.
error*What went wrong.
forbidden: you hold neitherkeys.mintnorkeys.manage, or onlykeys.manageand it widens or lengthens the key; it gives more than you hold or anexpires_atlater than yours, unlesskeys.managenarrows it; it widens or lengthens an app's key, or any key withnarrow_only, which also refuses a changedenforcement_override; or it namesenforcement_overridewithoutconfig.manage.
application/json- 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 itsexpires_at.
application/json- 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- 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- 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- response
An error response.
error*What went wrong.
request_too_large: the request body is larger than this instance accepts.
application/json- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X PATCH 'http://localhost:8600/keys/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "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}