Decionis API
Decionis for DevelopersGitHub
HomeAPI ReferenceSDKsContext Plugin
Hosted gateway

Grant a workspace's contracted hosted-enforcement permission

POST
/v1/hosted-gateway/workspaces/{id}/enforcement-contract

Records an operator-reviewed agreement as a workspace- and current-plan-bound hosted-enforcement operation permission. The expected plan is compared with current paid API access and the existing Account entitlement authority; it never changes billing, product plans or Account projections. Catalog plans already including enforcement need no exception and return a conflict. An explicitly prefixed owner-attestation reference remains labeled owner attestation in the durable audit. The customer ADMIN/OWNER approval, workspace beta gate, ownership proof, readiness and dedicated custody are still required. A successful receipt is not runtime activation. JSON only, bounded to 4096 bytes, ten requests per minute per address and twenty per hour per verified operator through the existing shared start limit. Every response is no-store. The request UUID binds action, org, grant where applicable, verified operator oid/tenant and normalized body. Exact retries return the original identity and audit references; rebinding returns 409. Operator identity, capability, credentials, consent, beta, billing changes and other extra fields are refused. Reasons and agreement references appear only in the transactional operator audit.

Authorization

OperatorEntraAuth
AuthorizationBearer <token>

A fleet operator's Microsoft Entra v2 access token for the "Decionis Operator API" app registration (Application ID URI api://decionis-operator), as az account get-access-token --scope api://decionis-operator/Operator.Act returns it: issuer https://login.microsoftonline.com//v2.0, audience the app's client id, scp holding Operator.Act, roles holding HostedGateway.Operator (or DECIONIS_OPERATOR_ENTRA_ROLE), and azp Azure CLI (04b07795-8ddb-461a-bbee-02f9e1bf7b46) or a client DECIONIS_OPERATOR_ENTRA_CLIENT_APPS names (403 OPERATOR_CLIENT_NOT_ALLOWED otherwise), verified against the tenant's JWKS. The app registration should make Operator.Act admin-consent only and require assignment on its enterprise application.

In: header

Path Parameters

id*string

The workspace (organization) UUID.

Formatuuid

Request Body

application/json

request_id*string
Formatuuid
expected_plan_code*string

Compare with the exact current paid plan. This never changes that plan.

Value in

  • "build"
  • "starter"
  • "defence"
  • "premium"
  • "scale"
  • "enterprise"
agreement_ref*HostedGatewayAgreementReference

Opaque reviewed agreement reference, or an explicitly labeled owner-attestation reference. No documents, credential URLs or whitespace.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$
Length1 <= length <= 160
reason*HostedGatewayContractReason

One line without control characters, trimmed before binding; at least ten characters after trimming.

Match^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$
Length10 <= length <= 500

Response Body

application/json

curl -X POST "https://example.com/v1/hosted-gateway/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/enforcement-contract" \  -H "Content-Type: application/json" \  -d '{    "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",    "expected_plan_code": "build",    "agreement_ref": "string",    "reason": "stringstri"  }'
{  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "grant_id": "a3c1da8e-13c6-4cab-955b-2120b58c2982",  "capability": "hosted_enforcement",  "plan_code": "string",  "status": "active",  "granted_at": "2019-08-24T14:15:22Z",  "revoked_at": "2019-08-24T14:15:22Z",  "grant_audit_event_id": "1d219059-c67e-474f-b153-784494a00f2b",  "revoke_audit_event_id": "9a3042de-b5a1-4af0-81ce-0453ce0a3ccf",  "activation_required": true}

Default off: exchange a role credential for a one-use TCP ticket POST

Default off. Native connectors and local tunnels supply the matching role credential in Authorization, never an organization API key. Rechecks ready route, current generation, role and the authorizing administrator's current paid active entitlement. A ticket expires in 60 seconds and is redeemed atomically once by the broker. At most 32 outstanding tickets per route, 120 requests/minute and 4096-byte JSON bodies. Compare route_id, tenant_host, gateway_url and the canonical resource/hash against local configuration before CONNECT. The service never receives TCP payloads or chooses a connector target.

Revoke a workspace's contracted hosted-enforcement permission POST

Withdraws the exact grant and retires only its provenance-bound keys, including delivered predecessors. In one audited transaction it invalidates dependent provisioning generations and leases and marks readiness blocked. It preserves requested/fleet modes, custody and history; it does not switch to SHADOW, remove a hostname, call the fleet or cancel in-flight actions. Withdrawal remains available with inactive billing. A later regrant needs new customer approval and a new key. An old revoke never withdraws a newer grant. JSON only, bounded to 4096 bytes, ten requests per minute per address and twenty per hour per verified operator through the existing shared start limit. Every response is no-store. The request UUID binds action, org, grant where applicable, verified operator oid/tenant and normalized body. Exact retries return the original identity and audit references; rebinding returns 409. Operator identity, capability, credentials, consent, beta, billing changes and other extra fields are refused. Reasons and agreement references appear only in the transactional operator audit.