Author a Policy#

A policy is what the authority runtime consults to reach a decision. This runbook walks you through authoring one as a governed draft: you structure a policy set, scope its rules, create the draft, and submit it for review. Promotion to a live version is covered in Deploy and Rollback.

Prerequisites#

• An API key (intended_live_…; legacy mrt_… also accepted) or a portal session with the authority:policy:write permission. Authoring and every lifecycle transition require it.
• The tenant id you are authoring for. Every policy call is tenant-scoped: the credential's tenant, the x-tenant-id header, and the body tenantId must all agree, or the request is rejected with 403 TENANT_MISMATCH.

How a policy decides#

Before you write rules, understand how they combine. The engine loads the tenant's policy sets, matches rules by their bindings and conditions, and resolves the outcome most-severe-wins (DENY > REQUIRE_APPROVAL > ESCALATE > ALLOW). When no rule matches, it defaults to DENY. Interpretation-layer (LIM) signals can only upgrade severity — never soften it. The risk score is baseRiskScore + (privileged?20) + (production?20) + (sensitive?15), capped at 100.

Policy set structure#

A policy set is the unit the engine evaluates. It is JSON, not YAML, and is carried inside the draft you create.

json
{
  "name": "prod-release-controls",
  "description": "Require approval for production release dispatches",
  "enabled": true,
  "version": 1,
  "defaultDecision": "DENY",
  "rules": [
    {
      "id": "rule_prod_release",
      "description": "Approval-gate prod release workflows",
      "intentTypes": ["workflow.dispatch"],
      "actions": ["dispatch release workflow"],
      "targetSystems": ["acme/platform-api"],
      "tools": ["github-actions"],
      "actorRoles": ["service", "deployer"],
      "environments": ["production"],
      "effect": {
        "decision": "REQUIRE_APPROVAL",
        "approvalRequirement": { "approverRoles": ["approver"], "minApprovals": 1 }
      }
    }
  ]
}

Fields#

Rule bindings and effect#

A rule matches an evaluation when every binding it declares is satisfied. Bindings left unset are wildcards.

A rule may also carry confidenceThresholds, budgetCeilings, and conditions. Its effect is { decision, approvalRequirement?, escalation? }, where decision is ALLOW / DENY / REQUIRE_APPROVAL / ESCALATE.

Step 1 — Create the draft#

Author through the governed lifecycle: create a draft rather than upserting the live set directly. Every lifecycle step appends to the audit ledger and requires authority:policy:write.

curl -X POST https://api.intended.so/policy/drafts \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "policyPackName": "prod-release-controls",
    "title": "Require approval for prod release dispatch",
    "createdBy": "user_admin",
    "policySet": {
      "name": "prod-release-controls",
      "version": 1,
      "defaultDecision": "DENY",
      "enabled": true,
      "rules": []
    }
  }'

curl -X PUT https://api.intended.so/policy/drafts/draft_123 \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "updatedBy": "user_admin",
    "policySet": { "name": "prod-release-controls", "version": 1, "defaultDecision": "DENY", "enabled": true, "rules": [ { "id": "rule_prod_release", "intentTypes": ["workflow.dispatch"], "environments": ["production"], "effect": { "decision": "REQUIRE_APPROVAL", "approvalRequirement": { "approverRoles": ["approver"], "minApprovals": 1 } } } ] }
  }'

Step 2 — Submit for review#

When the rules are complete, submit the draft for review. The reviewer who approves must hold authority:policy:write; separation of duties is a review-process control, not enforced by the endpoint.

curl -X POST https://api.intended.so/policy/drafts/draft_123/review \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "submittedBy": "user_admin",
    "comments": "Gating prod release dispatch behind one approval.",
    "simulationRunId": "sim_abc123"
  }'

Failure modes#

Common mistakes#

Next steps#

• Simulate Impact — preview the effect of the draft before you promote it.
• Deploy and Rollback — approve, deploy, and roll back.
• Policies API — the full route reference for /authority/policies and /policy/*.