Skip to content
Artist Alley

Finalize first-run setup (admin + site + SMTP)

POST
/setup/complete

One-shot transactional endpoint that creates the first admin user, writes site identity (display name, base URL), and optionally writes SMTP credentials. Only callable while no system.admin user exists; subsequent calls return 409.

SMTP is optional — pass null for the smtp field if email is not configured yet. The admin UI surfaces email-dependent features (password reset, notifications) as disabled until SMTP is filled in later.

Request Body required

Section titled “Request Body required ”
object
admin
required
object
username
required
string
>= 1 characters <= 50 characters
Example
admin
password
required
string format: password
>= 8 characters
email
required
string format: email
Example
admin@example.com
fullname
string
nullable
Example
Site Administrator
site
required
object
name
required
string
>= 1 characters <= 100 characters
Example
Acme Art Reviews
base_url

Absolute URL the site is reachable at. Used to build outgoing links (e.g., password-reset emails). May be empty at install time and filled in later.

string
Example
https://art.example.com
smtp
object
host
required
string
Example
smtp.example.com
port
required
integer
Example
587
encryption
required
string
Allowed values: none starttls tls
Example
starttls
username
string
password

Write-only. Provide to set or rotate the SMTP password; omit (or send empty string) on PATCH to keep the current value. The response never echoes this field — read password_set instead to check whether one is on file. Stored at rest encrypted via the AA_MASTER_KEY-backed atrest package; never sent back to clients.

string format: password
password_set

True when a password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.

boolean
from_address
required
string
Example
ArtSite <noreply@example.com>

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Setup complete; first admin is now active

object
ref
required
integer format: int64
username
required
string
fullname
string
nullable
email
string
nullable
usergroup
integer format: int64
nullable
auth_method
required

How the caller was authenticated for this request.

string
Allowed values: session token
language

User’s language pref (BCP47). Empty string = follow system / browser. Joined from user_profiles at /auth/me time so the frontend can hydrate the language store on first paint without a separate round-trip.

string
theme

User’s theme pref. Empty string = follow system. Same “join on /auth/me” rationale as language.

string
Allowed values: "" light dark
impersonated_by

Non-null when the session was minted via POST /admin/users/{ref}/impersonate. Carries the acting admin’s ref + username so the persistent “you are acting as @target” banner can render without a separate round-trip.

object
ref
required
integer format: int64
username
required
string

400

Section titled “400 ”

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

409

Section titled “409 ”

System already has an administrator; setup is not available

object
error
required

Human-readable error summary

string
Example
the request could not be completed

500

Section titled “500 ”

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed