Create an API key
Creates an API key and returns it with its plaintext key, shown only here. If the body names none of permissions, the five permission maps and sources, the key gets everything you hold; if it names any, the key holds only what it names.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
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 <= lengthsource*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 may have it as its own, and it can't change later.
1 <= length <= 200sources?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 <= 1000permissions?array<>The permissions to give the key, such as audit.read.
default_tier?stringThe tier an item this key creates goes to when the write names none. Leave it out for library.
"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?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.
enforcement_override?Enforcement levers for this key alone. Leave it out for none, so the key follows the instance's.
expires_at?stringWhen the key stops working, as an ISO 8601 date and time in the future. Leave it out for a key that never expires, or, if your own key expires, for one that expires when yours does. It can't be later than your own key's expires_at.
owner_key?booleantrue if the key is the owner's, not the app's you act for: it carries no oauth_client_id, and disconnecting or narrowing that app leaves it working. From an app, or a key an app made, it needs keys.manage.
falseReturns the new key with its plaintext key. When the local command creates an ordinary key from a body naming no permission, map or sources, the key holds every permission and *: write on every map, and claims no source.
application/json- response
A new API key, with its plaintext key.
id*stringUnique identifier for the key.
key*stringThe plaintext key, which you send as a bearer token. Save it: no other response shows it.
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:labelorsourceis missing, or a lever inenforcement_overridelackstypesorsources.validation_error: a field is invalid, such as an unknown permission level, more than 1,000sources, anexpires_atthat isn't a future time, anowner_keythat isn'ttrueorfalse, or asourceor claim startingoauth:orrestored:.
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 lackkeys.mintand aren't the local command; the body names a permission or map entry you don't hold, a claim, or another key's claim assource, that you can't grant, an ownsourcea connector holds withoutkeys.manage, anexpires_atpast your key's,owner_keyfrom an app withoutkeys.manage, orenforcement_overridewithoutconfig.manage.detailsnames it.
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.
conflict: another key that hasn't been revoked or expired already has thissourceas its own.details.sourcenames it. To let two keys write under one source, claim it insourcesinstead.
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 POST 'http://localhost:8600/keys' \ -H 'Content-Type: application/json' \ -d '{ "label": "string", "source": "string"}'{ "id": "01a10126-1e03-79a5-ba6f-f711fc6f0e95", "label": "reporting", "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, "key": "marfa_k1_qon-FTZpKQ_unXjMBmHlrP"}