Platform Onboarding

A fresh deployment starts with first-run setup on the platform container. First-run setup has two jobs:

• establish the deployment license; and
• create at least one platform administrator.

Both must be complete before the deployment is usable. A license token by itself does not create an operator account, and an operator account by itself does not make an unlicensed deployment usable.

The anonymous setup API is exposed at /api/platform/setup/v1 only while the durable setup gate is open. Once setup is complete, the setup adapter returns 404 and day-2 administration moves to authenticated Platform Admin calls under /api/platform/admin/v1.

This page assumes the platform container is part of the published enterprise image set from nexus.sphereon.com/edk-docker, and that Kubernetes installs use the edk-enterprise chart from https://nexus.sphereon.com/repository/edk-helm. Use the private Nexus coordinates for the enterprise stack.

The setup contract is in the Platform Setup API reference. Day-2 administration uses the Platform Admin API reference.

Choose an Onboarding Path

EDK supports three first-run paths. They all end in the same state: the license is active, the setup gate is closed, and the operator signs in through the platform authorization server at https://platform.<base-domain>/admin-console.

Path	Use when	What still has to happen locally
Onboarding web interface	A person is installing or evaluating the platform.	Use the web interface to generate or import the license, then create the operator account.
Setup REST API	The deployment is scripted, CI-driven, or managed by your own installer.	Call the setup endpoints directly in the same order the web interface uses.
Offline license resources	Sphereon has already issued a license token for this deployment, including evaluation, development, or production licenses.	Mount the license material, then either create the operator account through the setup API/web interface or mount complete operator provisioning material.

Onboarding Web Interface

The onboarding web interface is the recommended path for interactive first-run setup. In the Docker Compose walkthrough it is served separately from the platform API; the platform is configured with ONBOARDING_UI_BASE_URL, for example http://localhost:3003, so CORS and the operator sign-in callback point back to the UI.

The web interface drives the same setup API described below. It collects organization details, technical and administrator contacts, license material, and administrator details. When no license has been issued yet, it generates the complete license request artifact for out-of-band delivery to Sphereon. When Sphereon has already provided an offline license token, skip request generation and paste or upload the issued token in the license install step.

After the setup gate closes, open https://platform.<base-domain>/admin-console and sign in with the operator account. The UI redirects the operator through the platform authorization server and then to platform administration.

Setup REST API

Use the setup REST API when first-run setup is automated by scripts, Helm jobs, or an external installer. The API surface is anonymous only while setup is open.

Check setup readiness first:

GET  /api/platform/setup/v1/status
GET  /api/platform/setup/v1/license-request
GET  /api/platform/setup/v1/onboarding/state

If the deployment does not already have an issued license token, generate a license request:

POST /api/platform/setup/v1/license-request/generate

The generated response is the artifact sent to Sphereon. It contains the canonical request JSON, the local X.509 instance certificate, and the signature over the request JSON. License delivery is MANUAL in setup v1.

Install the issued token:

POST /api/platform/setup/v1/license/verify
POST /api/platform/setup/v1/license/install

Create the platform operator account before leaving first-run setup:

POST /api/platform/setup/v1/bootstrap

The operator can be based on the technical contact, the administrator contact, or a new natural person. The setup surface closes only after the license and operator-account steps have been completed.

Offline License Resources

Offline license resources are useful when Sphereon provides a ready-to-use license token instead of asking the customer to generate a license request first. This is valid for evaluation, development, and production deployments. For example, a customer may receive a time-limited unlimited license for development against the EDK containers, while a production deployment may receive a production license token through the same offline delivery channel.

There are two distinct offline patterns:

• License-only mount: mount the issued token as a runtime license source with license.path or license.token. Then use the onboarding web interface or setup REST API to create the operator account and close first-run setup.
• Full mounted bootstrap: mount the license token under platform.onboarding.license-token-path together with operator provisioning material. This activates the license, seeds the operator record, and closes the setup gate during boot.

Prefer the license-only mount when the operator should be created interactively or by an installer. Use full mounted bootstrap only when the mounted profile also provisions or activates the operator through the deployment's chosen account-activation path. This avoids closing the setup gate before an operator can sign in.

License-Only Mount

Mount the issued token and recipient key in the platform config directory, then point license.path at the token:

platform:
  config:
    mount-path: /app/config
license:
  path: /app/config/license-token.txt
  recipient:
    key-id: license-recipient
    private-key-path: /app/config/license-recipient.jwk.json
  trust:
    embedded:
      enabled: true

With this profile, /api/platform/setup/v1/status can report that a license source is configured, but first-run setup is still open until the operator account is created. Continue with the web interface or call:

POST /api/platform/setup/v1/bootstrap

Full Mounted Bootstrap

Use full mounted bootstrap only when the mount includes both license material and operator provisioning material. Offline license material is not limited to dev or trial deployments. The restriction is on mounted break-glass credentials: platform.onboarding.operator.initial-credential is a dev-mode shortcut and must not be used for production account activation.

Mount an application.yml plus the license materials under the platform config directory, for example:

platform:
  config:
    mount-path: /app/config
  onboarding:
    installation-base-domain: saas.example.com
    deployment-id: deployment-1
    license-token-path: license-token.txt
    recipient-key-path: license-recipient.jwk.json
    trust-bundle-path: license-root-ca.pem
    operator:
      email: operator@example.com
      display-name: Platform Operator
license:
  recipient:
    key-id: license-recipient
    private-key-path: /app/config/license-recipient.jwk.json
  trust:
    embedded:
      enabled: true

The platform container reads this through the normal YAML-backed config loader. platform.onboarding.license-token-path is resolved against platform.config.mount-path, activated through the same license store used by setup install, and then the setup gate is claimed. After boot, /api/platform/setup/v1/status returns 404; continue directly with operator sign-in.

Do not mount platform.onboarding.license-token-path without also providing a way to create or activate the operator account. Once that profile claims the setup gate, the anonymous setup API is no longer available. For local development only, a mounted platform.onboarding.operator.initial-credential can be used as a break-glass credential when the deployment mode permits it.

With the license active and the operator account available, continue with operator sign-in, or open https://platform.<base-domain>/admin-console directly.