Policies API#

Policy is what the authority runtime consults to reach a decision. This page covers three related surfaces:

1. POST /authority/evaluate — run the modern policy engine directly against a structured intent and get a decision back, without minting a token or executing anything.
2. /authority/policies — read and upsert the policy sets the engine evaluates.
3. /policy/* — the governed draft → review → deploy → rollback lifecycle for promoting policy changes safely.

How the engine decides#

The policy engine loads the tenant's policy sets, matches rules by their bindings and conditions, and combines results most-severe-wins (DENY > REQUIRE_APPROVAL > ESCALATE > ALLOW). When no rule matches, it defaults to DENY. Interpretation-layer (LIM) signals can only upgrade severity — they never soften a decision. The risk score follows the same formula as /intent: baseRiskScore + (privileged?20) + (production?20) + (sensitive?15), capped at 100.

Evaluate an Intent#

Request#

curl -X POST https://api.intended.so/authority/evaluate \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "intent": {
      "id": "9d2c…",
      "correlationId": "a9d903e0-8b45-4a2f-9d30-6f9ce7d04d78",
      "tenantId": "tenant_acme_prod",
      "adapterId": "github-actions-adapter",
      "adapterTarget": "acme/platform-api",
      "actor": { "id": "svc-ci-bot", "type": "service" },
      "targetSystem": "acme/platform-api",
      "proposedAction": "dispatch release workflow",
      "riskContext": {
        "baseRiskScore": 42, "policyCompliant": true,
        "requiresPrivilegedAccess": false, "touchesProduction": true,
        "containsSensitiveData": false,
        "github": { "owner": "acme", "repo": "platform-api", "ref": "refs/heads/main" }
      },
      "createdAt": "2026-06-06T12:00:00.000Z"
    },
    "context": {
      "tenantId": "tenant_acme_prod",
      "userId": "svc-ci-bot",
      "role": "service",
      "environment": "production",
      "tool": "github-actions",
      "targetSystem": "acme/platform-api"
    }
  }'

Response#

{
  "decision": "REQUIRE_APPROVAL",
  "policySetId": "ps_prod_controls",
  "triggeredRuleIds": ["rule_prod_change"],
  "rationale": ["production change requires approval"],
  "riskScore": 62,
  "requiredApproval": { "approverRoles": ["approver"], "minApprovals": 1 }
}

Policy Sets#

The rules /authority/evaluate consults live in policy sets.

curl "https://api.intended.so/authority/policies?tenantId=tenant_acme_prod" \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod"

A policy set is { id?, tenantId, name, description?, enabled, version, defaultDecision, rules[] }. Each rule carries bindings (intentTypes, actions, targetSystems, tools, actorRoles, environments), optional confidenceThresholds / budgetCeilings / conditions, and an effect ({ decision, approvalRequirement?, escalation? }).

Policy Lifecycle#

For governed promotion, work through drafts rather than upserting policy sets directly. Every step appends to the audit ledger and requires authority:policy:write.

Read#

Write#

Create a draft#

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 deploy",
    "createdBy": "user_admin",
    "policySet": { "name": "prod-release-controls", "version": 1, "defaultDecision": "DENY", "rules": [] }
  }'

Impact summary before you deploy#

GET /policy/drafts/:id/impact-summary returns a semanticDiff, an impact projection (sample size, changed-outcome rate, approval-load and token-issuance deltas, confidence, a lowData flag), and a rolloutSafety checklist with a recommendedMode of shadow / review / enforce. Read it before promoting a draft.

Next steps#

• Deploy a Policy — the operator workflow end to end
• Intents API — how these policies drive runtime decisions
• Authority Runtime Pipeline — the decision model in depth