DOCUMENTATIONv2

POST

Tenant and brand management

Create tenant

/api/v2/admin/tenants

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

PURPOSE + BUSINESS CONTEXT

Create a tenant identity and its first unpublished configuration revision.

WHEN THIS CALL IS USEFUL

Use when an authorized platform administrator is ready to provision a tenant identity and its first complete configuration revision.

OUTCOME · Create or advance

What changes

Creates the tenant and immutable revision 1 in DRAFT. It does not publish configuration, verify domains, configure DNS or TLS, allocate infrastructure, route traffic, or enable trading.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance tenant.
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 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 tenant only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required 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_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated stable key reused for retries of the same logical mutation.EXAMPLEpost-api-v2-admin-tenants-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.

change_summarybodyRequired

string · 1–320Retained human-readable reason for provisioning the initial DRAFT revision.EXAMPLEProvision Northstar test tenant.

configurationbodyRequired

TenantConfigurationFull revision 1 configuration: identity, brand, complete domain and entitlement sets, and non-secret settings. This is not a patch.EXAMPLE[object Object]

tenant_uuidbodyOptional

32-character lowercase hexadecimal identifier · nullableOptional caller-selected tenant identifier. Omit it to let Core allocate one.Explicit null acceptedEXAMPLEf8317aef81764e1f923037c1b76df8de

REQUEST

JSON body example

{
  "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"
  },
  "tenant_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB"
}

RESPONSES

Status and payload examples

201Tenant identity and immutable revision 1 created in DRAFT; no domain routing, infrastructure, traffic, or trading authority is activated.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 complete configuration, rationale, signature, identifier, or Idempotency-Key is malformed.Request must change · JSON RESPONSE+

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