Runbook — Installation identity and entitlement records

Audience: administrators of an Installation: the people who order capacity, import the vendor’s entitlement record and read the capacity status. Scope: reading the Installation identifier, importing and renewing an entitlement record offline, reissue after an Installation change, and what each status means.

Checked against src/Platform/StellaOps.Platform.WebService/Endpoints/PlatformInstallationEndpoints.cs, src/Platform/StellaOps.Platform.WebService/Doctor/EntitlementStatusCheck.cs, src/Cli/StellaOps.Cli/Commands/InstallationCommandGroup.cs, src/Cli/StellaOps.Cli/Commands/EntitlementCommandGroup.cs and src/Cli/StellaOps.Cli/Commands/EstateCommandGroup.cs on 2026-10-29 (SPRINT_20261027_004 ENT-7; stella entitlement import and show since VTR-4). Re-verify the routes with pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/Platform/__Tests/StellaOps.Platform.WebService.Tests/StellaOps.Platform.WebService.Tests.csproj -Class '*EntitlementImportEndpointsTests' and the CLI commands with the command guide’s own test command.

An entitlement record is closed licence administration between Stella Ops and the licensee of an order. It records the placement capacity and the term of the order for one Installation (record contract). It is advisory: no status blocks, degrades or stops a deployment, a scan, evidence or a running workload, and nothing is switched off when a term ends. The record is not for anyone outside the order, so do not pass it on, attach it to an evidence package or publish it.

The routes below are installation-wide. The import, the record list and the usage status require a global administrator (stellaops:admin=true) in addition to their scope; a tenant administrator gets 403.

1. Read the Installation identifier

The vendor names this identifier in every entitlement record, so send it through the order channel when you order or move capacity.

stella installation id

The command reads GET /api/v1/platform/installation (scope platform.setup.read); see the command guide for its options and its output. The identifier is a random UUID created on the first read and kept across restarts and upgrades. A restore of the Platform database keeps it; a new, empty Platform database creates a new one (section 5).

2. Authenticate a record before you import it (optional)

The vendor delivers the record as a .dsse.json file. You can check it offline, without importing it:

stella entitlement verify SOE-2026-000123-r1.dsse.json --installation-id <installation-id>

The command authenticates the record against the pinned vendor roots of purpose vendor-entitlement and prints what the record shows and what it does not show; see the command guide. The Platform import in section 3 runs the same checks again.

3. Import a record, and renew

Sign in to the CLI as the global administrator (a user-delegated login, not a service client), then import the file. Where Authority has several identity providers, name the one that holds the administrator, for example standard:

stella auth login --provider standard
stella entitlement import SOE-2026-000123-r1.dsse.json

The CLI sends the file unchanged and prints the stored revision. It exits 0 when the record is imported or this revision was already held, 5 when the Platform refuses it (the refusal code and reason are printed, table below), 7 when the file does not exist and 8 when the request fails (no permission or no Platform). Add --json for a machine-readable result (command guide).

API alternative. The same import is POST /api/v1/platform/entitlements with the global administrator’s token. The token needs the scope platform.entitlements.admin, which the Console client and the stellaops-cli client allow.

curl -sS -X POST "https://stella-ops.example.internal/api/v1/platform/entitlements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @SOE-2026-000123-r1.dsse.json

Answer	Meaning
`201 Created`	The record is stored; the body is the stored revision.
`200 OK`	The same record was already accepted; nothing changed.
`403 Forbidden`	The caller is not a global administrator, or lacks the scope.
`413`	The body is larger than 64 KiB; the file is not an entitlement record.
`422` `entitlement_refused`	The record was refused; `refusal` gives the code and `detail` the reason (table below).

`refusal`	What to do
`wrong_installation`	The record names another Installation. Compare it with `stella installation id` and ask the vendor for a revision that names this Installation (section 5).
`revision_rollback`	The Installation already holds a higher revision of this serial, or this revision with other content. Import the latest revision you received.
`unknown_key`, `issuer_key_mismatch`, `signature_invalid`	The record is not signed by a pinned vendor entitlement root, or it was changed after signing. Ask the vendor to deliver it again; do not edit the file.
`no_trust_roots`	Platform has no usable vendor entitlement root. Mount the vendor trust-root set (below) and import again.
`malformed_envelope`, `unsupported_payload_type`, `missing_signature`, `non_canonical_payload`, `schema_violation`	The file is not a v1 entitlement record. Ask the vendor to deliver it again.

Platform reads the vendor trust-root set at each import from the directory named by STELLAOPS_VENDOR_TRUST_ROOTS, or from trust/vendor-roots/ beside the Platform binary (vendor trust-root set). Only roots of purpose vendor-entitlement authenticate a record.

Renewal and capacity changes. The vendor delivers a renewal, a capacity change or a new order reference as the next revision of the same serial. Import it the same way: the higher revision supersedes the lower one completely, and the lower one stays as history. Separate serials are separate subscriptions, and their recorded capacities add up while each is within its term.

List the records. stella entitlement show prints the capacity status and every accepted revision, the highest revision of each serial first and marked current, with the state of its recorded term. The API alternative is GET /api/v1/platform/entitlements (global administrator and platform.setup.read), which gives the term state as notYetValid, current or expired.

4. Read the status

stella entitlement show
stella estate placements --installation

stella entitlement show prints the capacity status that combines the managed-placement count with the records, as the global administrator. stella estate placements --installation reads the count alone from the Release Orchestrator (ops.admin): the total, the recorded and the declared placements, and the detection signals it does not count yet (command guide, which also lists the operations that retire or declare a placement). The API alternative for the status is GET /api/v1/platform/usage/placements (global administrator, platform.setup.read and a tenant context). In the Console, Setup > Usage (/setup/usage) shows the same status, the installation identity and the entitlement records with an Import record action to the global administrator (the import also needs platform.entitlements.admin), and shows every user with orch:read or release:read the recorded, declared and total placements of their own tenant per environment and each placement; a user holding orch:operate can retire a recorded placement, withdraw a declaration and declare a placement the product does not detect. A read the signed-in user may not make is shown as such, never as an empty list or a zero count. When the count cannot be read, the route answers 503 placement_count_unavailable with a reason and no status: it never guesses a count.

Doctor reports the record state without the count: the check doctor.platform.entitlement.status appears in the Console Doctor dashboard and at platform-web’s /doctor/platform-web/checks, as Information or Warning, never as a failure.

Status	Meaning	What to do
`over`	The placement count is above the effective capacity.	Reduce the managed placements or order more capacity. The LICENSE permits an inadvertent excess for 14 days after you become aware of it, provided usage is reduced or capacity obtained promptly. Nothing is blocked.
`expired`	No record is within its term; the latest one ended, and the count is within the free allowance of 20.	Renew if you need paid capacity; until then the free allowance applies. The installation keeps running.
`expiring`	A record ends within 30 days, and the count is within capacity.	Renew before the end date; a renewal keeps the paid capacity. Nothing is switched off when the term ends.
`within`	A record is within its term with more than 30 days left, and the count is within capacity.	Nothing.
`none`	No record is on file, and the count is within the free allowance of 20.	Nothing, unless you need more than the free allowance.

The status reflects only the records imported into this Installation: import every revision you receive. It neither extends nor denies any right under your order.

5. Reissue after an Installation change

An Installation keeps its identifier through restarts, upgrades and a restore of its Platform database. It gets a new identifier when Platform starts on a new, empty database, for example a rebuild on another host without a restore.

Read the new identifier with stella installation id.
Send it to the vendor through the order channel with the serial of the subscription.
The vendor issues the next revision of the same serial naming the new identifier.
Import that revision into the new Installation (section 3). It is refused with wrong_installation at any other Installation, including the former one, where the revision it replaces stays on record.