Owner

Claim the instance

Creates the one owner using a machine-issued setup code or setup-only browser session. A claimed instance never reopens setup. A claim from the instance's own origin, which the setup page sends, also signs the owner in with a session cookie.

POST
/owner

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

The username the owner signs in with: 1 to 64 letters a to z, numbers, dots, dashes and underscores. Marfa stores it in lowercase, with spaces at each end trimmed.

Lengthlength <= 64
password*string

Password for the new owner.

name?string

Display name. Defaults to the username when omitted or blank.

Lengthlength <= 200
email?string

The owner's email address. It plays no part in signing in. Marfa stores it in lowercase, with spaces at each end trimmed.

Formatemail
Lengthlength <= 254
code?string

Machine-issued setup code. Omit when using a setup-only browser session.

Response body

About errors

The new owner can sign in. A claim from the instance's own origin also sets the owner session cookie, unless the sign-in that follows the claim fails. A claim with no Origin header, such as a script's, sets none.

application/json
  1. response

The single owner of the instance.

id*string

Unique identifier for the owner.

username*string

The username the owner signs in with.

email*|

The owner's email address, or null when none is set. It plays no part in signing in.

name*string

Display name of the owner.

avatar*|

The address of the owner's avatar on this instance, or null when none is set. Fetch it with GET /profile/avatar.

created_at*string

When the owner was created, in UTC.

Owner details are invalid, or the body has a field this endpoint doesn't take.

application/json
  1. response

An error response.

error*

What went wrong.

Setup proof is invalid, expired, or replaced.

application/json
  1. response

An error response.

error*

What went wrong.

The browser origin or transport is not permitted.

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.

The instance has already been claimed.

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.

The address has used its setup-code attempts.

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.

curl -X POST 'http://localhost:8600/owner' \  -H 'Content-Type: application/json' \  -d '{  "username": "string",  "password": "string"}'
About errors
{  "id": "01926a3c-4b1d-7e52-9a8f-3c5d7e1b2a40",  "username": "alex",  "email": "alex@example.com",  "name": "Alex Example",  "avatar": null,  "created_at": "2026-10-03T09:30:00.000Z"}