Setup¶

Bootstrap endpoint for initializing the platform for the first time.

Base path: /api/setup

Endpoints¶

Method	Path	Auth	Description
`POST`	`/api/setup/first-run`	Public	Create the first platform admin

POST /api/setup/first-run¶

Create the first PlatformAdmin user. This endpoint is self-disabling — it succeeds only when no Owner or PlatformAdmin exists in the database yet.

After the first successful call, every subsequent call returns 409 Already initialized.

Authentication: Not required.

Request body:

{
  "email": "admin@yourcompany.com",
  "password": "StrongPassword123!",
  "name": "Alice Johnson"
}

Field	Type	Required	Constraints
`email`	string	Yes	Valid email address
`password`	string	Yes	Minimum 8 characters
`name`	string	Yes	Full display name (space-separated first/last)

Response 201:

{
  "data": {
    "id": "user-cuid",
    "email": "admin@yourcompany.com",
    "role": "PlatformAdmin"
  }
}

Error responses:

Code	Condition
`409`	A platform-level user already exists — setup is already complete
`500`	User creation failed or database schema not migrated

Usage¶

Run this endpoint once after the first deployment and database migration:

curl -X POST https://your-backend.com/api/setup/first-run \
  -H "Content-Type: application/json" \
  -H "X-Client-Key: cak_your_key" \
  -d '{
    "email": "admin@yourcompany.com",
    "password": "StrongPassword123!",
    "name": "Alice Johnson"
  }'

After completion, sign in using POST /api/auth/sign-in/email with the credentials you provided.