DOCUMENTATIONv2

POST

Tenant and brand management

Create revision

/api/v2/admin/tenants/{tenant_uuid}/configuration-revisions

AUTHENTICATIONBearer token · admin:tenants:writeAUTHORITATIVE OWNERtenant-configuration-serviceCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Create a draft revision containing domain, branding, navigation, feature, and entitlement changes.

WHEN THIS CALL IS USEFUL

Use after reading current tenant detail when a complete desired tenant configuration is ready to retain as a new immutable DRAFT.

OUTCOME · Create or advance

What changes

Creates one immutable DRAFT from the supplied base_configuration_version. Effective tenant state remains unchanged.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance revision.
Separates draft configuration work from effective tenant behavior so changes can be reviewed, audited, published atomically, and reverted through a new draft.

ISOLATION + AUTHORITY

Platform administrator, tenant, domain, certificate, brand, navigation, feature declaration, entitlement source, configuration revision, review, publication, and application-domain authority remain distinct. A tenant configuration or entitlement cannot enable frozen trading controls, matching, prediction execution, ingress, publisher activity, market status, traffic, wallet signing, or settlement authority.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required tenant_uuid (path), base_configuration_version (body), configuration (body), change_summary (body) exactly as defined by the live contract.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the tenant UUID, current published configuration version, complete desired configuration, administrator authority, and any domain-owned policy that cannot be granted by tenant settings.

WHAT TO DO NEXT

Open the returned tenant or draft revision and inspect its complete configuration and validation posture.
Use the separate publication operation only after review; creation of a tenant or draft does not make the configuration effective.

AGENT GUIDANCE

Use revision only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required tenant_uuid (path), base_configuration_version (body), configuration (body), change_summary (body) exactly as defined by the live contract.
Distinguish tenant creation, draft revision, validation, review, publication, supersession, reversion draft, domain verification, certificate readiness, entitlement visibility, and domain-owned authorization.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.

MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing admin:tenants:write authority.EXAMPLEBearer hc_live_…

tenant_uuidpathRequired

identifierStable tenant uuid selecting the exact resource addressed by this route.EXAMPLEtenant-uuid-01

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated stable key reused for retries of the same logical mutation.EXAMPLEpost-api-v2-admin-tenants-tenant-uuid-configuration-revisions-request-001

X-Request-IDheaderOptional

stringOptional caller correlation identifier. The gateway emits the effective value on the response.

Content-DigestheaderRequired

stringRFC 9530 sha-256 digest of the exact transmitted request-body bytes.

Signature-InputheaderRequired

stringRFC 9421 sig1 input covering @method, @path, content-digest, content-type, and idempotency-key, with created, expires, nonce, keyid, and alg=ed25519.

SignatureheaderRequired

stringRFC 9421 sig1 Ed25519 signature made by an active key registered to the bearer client.

base_configuration_versionbodyRequired

integer · ≥1Current published tenant configuration version. A stale value fails atomically with 409.Schema range: 0 to unboundedEXAMPLE3

change_summarybodyRequired

string · 1–320Retained operator summary explaining why this complete revision is being proposed.EXAMPLERefresh production presentation configuration.

configurationbodyRequired

TenantConfigurationFull desired tenant configuration. Draft revisions are immutable; create another draft to make another change.EXAMPLE[object Object]

REQUEST

JSON body example

{
  "base_configuration_version": 0,
  "change_summary": "example-change-summary",
  "configuration": {
    "brand": "example-brand",
    "domains": [
      {
        "hostname": "example-hostname",
        "is_primary": true,
        "purpose": "example-purpose",
        "redirect_hostname": "example-redirect-hostname"
      }
    ],
    "entitlements": [
      {
        "capability_code": "example-capability-code",
        "policy": "example-policy",
        "status": "example-status"
      }
    ],
    "identity": {
      "description": "example-description",
      "environment": "example-environment",
      "lifecycle_status": "example-lifecycle-status",
      "name": "example-name",
      "owner_workspace_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
      "parent_tenant_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
      "region_code": "example-region-code",
      "symbol": "example-symbol",
      "tenant_key": "example-tenant-key"
    },
    "settings": "example-settings"
  }
}

RESPONSES

Status and payload examples

201New immutable DRAFT containing the complete desired configuration; the effective tenant projection remains unchanged.Mutation completed · JSON RESPONSE+

{
  "administrators": [
    "example-administrator"
  ],
  "assignment": "example-assignment",
  "assignment_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
  "change_summary": "example-change-summary",
  "changes": [
    "example-change"
  ],
  "configuration": "example-configuration",
  "configuration_hash": "example-configuration-hash",
  "configuration_version": 1,
  "event_type": "example-event-type",
  "replayed": true,
  "revision": 1,
  "revision_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
  "status": "example-status",
  "tenant_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB"
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then open the returned tenant or draft revision and inspect its complete configuration and validation posture.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Persist returned identifiers, versions, commitments, and receipts. Refresh the tenant and brand revisions, domain verification, entitlement and administrator state, and any dependent workspace or application bindings.

400The tenant identifier, complete configuration, base version, rationale, signature, or Idempotency-Key is malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}