API reference · API 1.0.0

Licence

This platform's licence.

get /api/v1/licence

This platform's licence

Operation licence_get · bearer token

The licence state as the licence gate sees it, plus what the installed document says. growth_allowed, writes_allowed and sp_mode_enabled are the gate's own verdicts for this state. The full serial and the bundle are returned only to a principal holding licence-admin-global; the serial is masked for everyone else. Never licence-gated.

Responses

  • 200

    The licence.

    application/json → Licence
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
put /api/v1/licence/bundle

Install a licence bundle

Operation licence_bundle_put · bearer token

Verifies the acplic1. bundle against the pinned roots (the development root is trusted only on sandbox and dev estates), checks that it is bound to this portal's instance id, and installs it in place of the installed document.

EPOCH RULE (unchanged from the portal's Licence page): a bundle installs only when its licence_epoch is HIGHER than the installed document's. The epochs are compared regardless of licence_id, so a bundle for a different licence with a lower or equal epoch is refused too. Re-sending the installed bundle is therefore a 409 stale_epoch with already_installed: true; another document whose epoch is not higher gets already_installed: false.

A document bound to another NAME is installed, and the portal then reports DOMAIN_MISMATCH. Never licence-gated: this works in every state, LOCKED included. There is no operation that removes a licence. The bundle is never logged and never written to the audit log; the one audit row per install holds the licence id, the epoch and the document digest.

Request bodyrequired

application/json

Schema LicenceBundlePut

A licence bundle to install in place of the installed licence document.

NameTypeDescription
bundlerequired string

SENSITIVE. The acplic1. bundle ATAILA issued for this portal.

min length 1 · max length 65536

Responses

  • 200

    The licence was installed; it is as shown.

    application/json → LicenceInstalled
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    The portal already holds a document with the same or a higher epoch (stale_epoch); nothing was installed. installed_epoch and installed_document_digest describe what is installed, and already_installed is true when the bundle sent IS the installed document (same digest), false when it is another one with an epoch that is not higher.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    The bundle does not verify (bundle_invalid) or is bound to another portal instance (instance_mismatch), or the body is invalid.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/licence/socket-facts

The socket census

Operation licence_socket_facts · bearer token

The latest census measurement per node and whether the census hash chain is intact. Read-only: the census itself runs on its own schedule and cannot be started through this API.

Responses

  • 200

    The socket facts.

    application/json → SocketFacts
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID

Rendered from openapi-v1.json, platform release 1.0.187. Your installation serves the contract of its own version at /api/v1/openapi.json.