Site Activation

A site server is the Consystence server running on your own infrastructure. It runs and serves operators on its own; to link it to your hosted tenant, you activate it once with a one-time site-activation code. Activation attaches the server to your tenant, joins it to the site the code was issued for, and gives it what it needs to sync to the cloud. This page covers getting a code, the server’s setup endpoints, and what activation does.

Tenants and site servers

Tenants are created by the Consystence account service (account.consystence.com), which places each tenant on a hosting cell and makes the person who creates it its first owner; see Tenant provisioning. A cloud-linked site server joins an existing tenant through that tenant’s cloud cell, which checks the activation code with the account service on the server’s behalf. A standalone server that will not link to the cloud is provisioned from a tenant bootstrap file instead (see On-prem deployment).

sequenceDiagram
  participant O as Owner (account console)
  participant A as Account service
  participant I as Installer
  participant S as Site server
  participant C as Cloud cell
  O->>A: Declare the site, generate a code
  A-->>O: One-time code (shown once)
  O-->>I: the code, passed on out of band
  I->>S: POST /api/setup/site-activation { code, siteCode }
  S->>C: code + install id + site
  C->>A: check and redeem the code
  A-->>C: activation bundle
  C-->>S: bundle + site→cloud sync key
  S-->>I: 200 configured

Get an activation code

An organisation owner declares the site for the tenant in the account console, then generates a one-time site-activation code for that declared site. The code is shown once, expires in 7 days and works once, and it is bound to the site it was issued for. Codes are issued for an organisation’s tenants; they cannot be issued for a personal sandbox or a trial tenant. See Licensing for the licence side of the flow.

The setup endpoints

A site server’s setup surface is three endpoints:

Endpoint	Purpose
`GET /api/setup/status`	The server’s mode, version and activation state (`Fresh` or `Active`) and, once activated, its tenant.
`POST /api/setup/site-activation`	Activate the server with a one-time code (below).
`POST /api/setup/reset`	Return a site server to its fresh-install state so it can be activated again. This is a Consystence support operation, not available to tenant credentials.

The one-time code is the server’s credential for activation.

Activate the server — `POST /api/setup/site-activation`

First set Server:CloudUrl to your tenant’s cloud address (see Cloud link). Then post the code on the server host:

curl -s -X POST http://127.0.0.1:8080/api/setup/site-activation \
  -H 'Content-Type: application/json' \
  -d '{ "code": "<activation code>", "siteCode": "line-4", "siteName": "Line 4" }'

Field	Meaning
`code`	The one-time activation code (required).
`siteCode`	The code of the site the activation code was issued for. A different site code is refused and nothing is created. Without it, the server is attached to its tenant but joins no site and receives no site→cloud sync key.
`siteName`	Optional display name, used when the cloud first creates the site’s record.

The server reads its write-once install id locally (activation never mints one), sends the code, install id and site to its tenant’s cloud cell ({Server:CloudUrl}/api/provision/site-activation), and applies the activation bundle that comes back (verify, persist, then Configured). It answers 200 with { "status": "configured", "orgSlug": "…" }.

Condition	Status
Not a site-mode server; missing `code`; `Server:CloudUrl` not configured	`400`
The cloud refused the activation or could not be reached, or the returned bundle could not be applied — the response carries the reason	`400`
Server already configured, or a reset’s cleanup is still running	`409`

The cloud refuses an activation, and nothing is created, when:

the code was issued for a different site — use the site code the activation code was issued for;
the site code cannot be registered to your organisation — declare the site under a different code and generate a new code for it;
the code is unknown, has expired or was used by another server — generate a new code;
the cloud could not register the site or reach the account service — retry.

Activation is safe to retry from the same server until the code expires: if the response is lost after the code is used, the same server can present the code again and recover its bundle. A code already used by a different server is refused.

What activation gives the server

Its tenant identity, and the organisation sign-in settings it validates tokens against.
Its site: the server joins the declared site the code was issued for, and the cloud creates the site’s record if it does not exist yet.
A site→cloud sync key, for the first server activated for a site. That server then syncs the site’s historian to the cloud (see Historian), and site-model changes once model sync is enabled.
A signed licence, when the organisation has a SiteServer seat available. The licence is account-signed and verified on the server, offline. Without an available seat the server still enrols: a licence is never a condition of enrolment.

Activation needs the server to reach its cloud cell once. After that the server verifies its licence offline and keeps running without a cloud connection. Activation for fully air-gapped sites is roadmap.

Where this fits

Tenant provisioning — how tenants are created and deleted.
On-prem deployment — installing and configuring a site server.
Edge deployment — edges connect through their site server.
The rendered API reference lists GET /api/setup/status; the activation and reset endpoints are documented on this page.