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.
__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.
vendor*stringThe namespace, as app.<vendor>.
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
client_id*stringThe OAuth client ID of the app to give the namespace to. GET /grants lists each app's client_id.
1 <= lengthReturns the vendor binding as it now reads.
application/json- 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*stringThe 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*stringWhen the namespace was first held, or when it was given to the app that holds it.
date-timevalidation_error: the vendor is not anapp.<vendor>namespace, the body is malformed,client_idis 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_idis missing.
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: the credential lacksgrants.manage, anddetails.required_scopenames 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- response
An error response.
error*What went wrong.
not_found: no app with that client ID has registered on this instance, anddetails.client_idnames 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.
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 PUT 'http://localhost:8600/app-vendors/string' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "string"}'{ "vendor": "app.acme", "client_id": "01a10127-d974-7c54-8cc4-5b1e0f3c2a10", "claimed_at": "2026-11-20T09:30:00.000Z"}