---
title: "Create a brokered on-prem setup session"
method: POST
path: "/onprem/v1/setup-sessions"
tags: ["onprem", "onprem", "__public__"]
---

# Create a brokered on-prem setup session

`POST /onprem/v1/setup-sessions`

## Request body

- SetupSessionCreateRequest
  - `cloud_provider` 'aws' | 'gcp' | 'azure', required — Customer cloud target, e.g. gcp, aws, or azure
  - `ingress_target` string, required — Ingress hostname or IP address the Definite-hosted DNS record should target
  - `requested_slug` string, nullable — Optional preferred DNS label. If taken, the broker allocates a unique suffix.
  - `release_version` string, nullable — definite-onprem release version being installed
  - `setup_token` string, password, required — Broker setup token shared with the first-run installer

## Response `201`

Success

- SuccessResponseSetupSessionResponse
  - `success` true, required — Flag for it request was successful
  - `data` SetupSessionResponse, required
    - `setup_id` string, required
    - `fqdn` string, required
    - `url` string, required
    - `ingress_target` string, nullable — Ingress hostname or IP the brokered DNS record currently targets. Lets an installer detect when the live ingress LoadBalancer has changed and re-point DNS.
    - `dns_status` 'created' | 'pending' | 'ready' | 'failed', required
    - `license_key` string, nullable — Raw license key. Returned only by the create endpoint and never by status polling.
    - `license_id` union
      - string, uuid
      - string
    - `expires_at` string, date-time, required
    - `status` 'license_pending' | 'dns_pending' | 'ready' | 'failed', required
    - `error` string, nullable
  - `meta` ResponseMeta
    - `requestId` string — Unique request identifier for tracing
    - `timestamp` string, date-time — Response timestamp (UTC)
    - `durationMs` integer, nullable — Request processing time in milliseconds

## Other responses

- `400` — Validation Bad Request
- `401` — Auth Invalid Token
- `403` — Forbidden Insufficient Permissions
- `409` — Resource Conflict
- `422` — Validation Failed
- `426` — Business Quota Exceeded
- `500` — Internal Error

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/3943d8deb3be/schema)