API keys

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.

POST
/keys

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

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
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 may have it as its own, and it can't change later.

Length1 <= length <= 200
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
permissions?array<>

The permissions to give the key, such as audit.read.

default_tier?string

The tier an item this key creates goes to when the write names none. Leave it out for library.

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?

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?string

When 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?boolean

true 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.

Defaultfalse

Response body

About errors

Returns 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
  1. response

A new API key, with its plaintext key.

id*string

Unique identifier for the key.

key*string

The plaintext key, which you send as a bearer token. Save it: no other response shows it.

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: label or source is missing, or a lever in enforcement_override lacks types or sources.
  • validation_error: a field is invalid, such as an unknown permission level, more than 1,000 sources, an expires_at that isn't a future time, an owner_key that isn't true or false, or a source or claim starting oauth: or restored:.
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 lack keys.mint and aren't the local command; the body names a permission or map entry you don't hold, a claim, or another key's claim as source, that you can't grant, an own source a connector holds without keys.manage, an expires_at past your key's, owner_key from an app without keys.manage, or enforcement_override without config.manage. details names it.
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.

  • conflict: another key that hasn't been revoked or expired already has this source as its own. details.source names it. To let two keys write under one source, claim it in sources instead.
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 POST 'http://localhost:8600/keys' \  -H 'Content-Type: application/json' \  -d '{  "label": "string",  "source": "string"}'
About errors
{  "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"}