Apps

Give a vendor to an app

Gives an app.<vendor> namespace to the app you name by client ID, which then registers types under it and reaches its items. Use it when an app's client ID changes. Requires the owner's browser session, or grants.manage on a key the owner made.

PUT
/app-vendors/{vendor}

Authorization

cookie__Host-marfa_session<token>

The owner's browser sign-in, which only the sign-in pages read: here, the passkey doors. On plain HTTP on this machine, the cookie is marfa_session. Writes require this instance's Origin, and changes require authentication within fifteen minutes. Apps cannot use this authority.

Path parameters

vendor*string

The namespace, as app.<vendor>.

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
client_id*string

The OAuth client ID of the app to give the namespace to. GET /grants lists each app's client_id.

Length1 <= length

Response body

About errors

Returns the vendor binding as it now reads.

application/json
  1. response

An app.<vendor> namespace and who holds it. Only the app that holds it registers types under it, and that app reaches the namespace's items without a scope that names them. While the owner holds it, no app does until the owner gives it to one.

vendor*string

The namespace, as app.<vendor>.

client_id*|

The OAuth client ID of the app that holds the namespace, or null while the owner holds it because no one app is known to have made its types.

claimed_at*string

When the namespace was first held, or when it was given to the app that holds it.

Formatdate-time
  • validation_error: the vendor is not an app.<vendor> namespace, the body is malformed, client_id is not a string, the body has a field this endpoint doesn't take, or the query has a parameter it doesn't take.
  • missing_required_field: client_id is missing.
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: the credential lacks grants.manage, and details.required_scope names it, or it is an app's sign-in or a key an app made, which never gives a namespace to an app.
application/json
  1. response

An error response.

error*

What went wrong.

  • not_found: no app with that client ID has registered on this instance, and details.client_id 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.

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 PUT 'http://localhost:8600/app-vendors/string' \  -H 'Content-Type: application/json' \  -d '{  "client_id": "string"}'
About errors
{  "vendor": "app.acme",  "client_id": "01a10127-d974-7c54-8cc4-5b1e0f3c2a10",  "claimed_at": "2026-11-20T09:30:00.000Z"}