Skip to content

Setup API

3 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/setup

First-run setup state

200 while the install has no organisation; 404 once setup is complete.

Access
Public (no sign-in)

Responses

200 Success. object

  • requiredtruerequired
  • 404 not_found

POST/api/v1/setup

Complete first-run setup

Creates the organisation and its owner in one transaction, invalidates the setup code and signs the owner in (MFA enrolment is offered next). Requires the code in the `x-setup-code` header.

Access
Public (no sign-in)

Request body

application/json, object, required

  • organisationNamestringrequired

    min length 2 · max length 200

  • ownerNamestringrequired

    min length 1 · max length 200

  • ownerEmailstringrequired

    max length 320

  • ownerPasswordstringrequired

    max length 1024

Responses

201 Success. object

  • organisationIdstring (uuid)required
  • organisationSlugstringrequired
  • ownerUserIdstring (uuid)required
  • 400 validation_failed
  • 401 invalid_setup_code
  • 404 not_found
  • 409 conflict
  • 429 rate_limited

POST/api/v1/setup/verify

Check the one-time setup code

Send the code from the server logs in the `x-setup-code` header. Five wrong codes from one IP block it for 15 minutes.

Access
Public (no sign-in)

Responses

204 No content.

  • 401 invalid_setup_code
  • 404 not_found
  • 429 rate_limited