---
id: tenant-engine.write-api.mutate
name: tenant-engine Write API authorization
namespace: tenant-engine:tenant
version: v1
status: ready
package: flexauth.tenant_engine.write_api
actions:
  - tenant.create
  - tenant.role.grant
  - tenant.role.revoke
  - tenant.plan.assign
  - tenant.update
  - tenant.retire
  - tenant.reactivate
  - tenant.guardrail.read
  - tenant.guardrail.set
owner: team:platform-security
fixtures:
  - policy_fixtures.yaml
caring:
  profile: caring-0.4.0-rc2
  enforce: false
  canonical_roles:
    - Operator
  organization_relations:
    - ServiceProvider
  scopes:
    - level: Platform
      id: platform:tenant-engine
      tenant: tenant:platform
  planes:
    - Identity
    - Policy
    - Audit
  capabilities:
    - Create
    - Grant
    - Revoke
    - Bind
    - EditAny
    - Archive
    - Restore
    - View
    - Audit
  exposure_modes:
    - Metadata
  conditions:
    - Logged
  restrictions:
    - PrivilegeEscalationBlocked
activation:
  mode: local
metadata:
  source: examples/tenant-engine/policy_package.md
  flex_auth_contract: protected-system-v0
---

# tenant-engine Write API authorization

This package authorizes `tenant-engine`'s write API
(`TEN-WP-0003`'s `authz.FlexAuthWriteAuthorizer`). `tenant-engine` keeps
custody of tenant records, role-grant audit trails, and plan assignments;
flex-auth decides whether a specific write is allowed now.

**Scope note:** this policy governs *who may call tenant-engine's admin
API* (an operator/service-identity question) — it does not evaluate a
*tenant's* capability roles (`PLTF`/`IAM`/`VEN`/`CUS`, ADR-0014). Those are
tenant state a *different* protected system's policy might consult via
`tenant-engine`'s live-lookup endpoint (`FLEX-WP-0008-T03`); conflating the
two would authorize the wrong thing.

## Lifecycle actions (FLEX-WP-0010)

`tenant.update`, `tenant.retire`, and `tenant.reactivate` gate
`tenant-engine`'s lifecycle endpoints (`PATCH /tenants/{id}`,
`POST /tenants/{id}/retire`, `POST /tenants/{id}/reactivate`). The action
strings are the exact values `authz.FlexAuthWriteAuthorizer` sends; they are
coordinated between the two repos, not independently chosen here.

They are three actions rather than one `tenant.write` because tenant-engine
deliberately separated them so policy *can* one day permit renaming a tenant
without permitting retiring it. Under the current model that separation is a
seam, not a difference — see the decision below.

### Decision: `tenant.retire` does not require stricter authorization yet

**Decision (FLEX-WP-0010-T02, 2026-08-10): no.** `tenant.retire` is
authorized by the same rule as the other six actions.

Reasoning:

1. **There is nothing stricter to check.** The subject set is exactly one
   service identity (`tenant-engine`), there is no second operator to
   distinguish from, and requests carry no `assurance` claim — the
   `CheckRequest` shape from FLEX-WP-0008 has no field that could
   differentiate retirement from an update. A "stricter" rule today could
   only be stricter in name.
2. **A rule that cannot fail is worse than no rule.** Adding a condition
   that the single known caller always satisfies would read, to a later
   reviewer, as though retirement were separately controlled when it is
   not. That is a false assurance in a policy package whose job is to be
   inspectable.
3. **The blast radius is recoverable.** Retirement is reversible by design
   via `tenant.reactivate`, and tenant-engine hard-deletes nothing. A
   wrongly allowed retirement suspends new grants and plan changes until
   reactivated; it does not destroy tenant state.
4. **The seam is already cut.** Because the three actions are distinct
   strings in `valid_actions`, tightening `tenant.retire` later is an
   additive change to this package — no consumer change, no request-shape
   change, no coordination round with tenant-engine.

**Revisit when** `KEY-WP-0005` gives callers an `assurance`-bearing identity,
**or** when a second operator subject is registered against
`system: "tenant-engine"` — whichever comes first. At that point the honest
options are an assurance floor on `tenant.retire` or a distinct
`group:tenant-engine-lifecycle` membership requirement; both are one rule in
`allowed` plus a `first_denial` branch.

## Guardrail actions (FLEX-WP-0014)

`tenant.guardrail.read` and `tenant.guardrail.set` gate tenant-engine's
ceiling surface (`GET /tenants/{id}/guardrails`,
`PUT`/`DELETE /tenants/{id}/guardrails/{limit_key}`). The strings are the
exact values `authz.FlexAuthWriteAuthorizer` sends. Resource type is
`guardrail`; `resource.id` is still the tenant id.

They are two actions because a PDP must be able to read ceilings without
being able to change them. tenant-engine is a data source, never a decision
maker; flex-auth is the intended reader.

### Decision: use the read/write split now

**Decision (FLEX-WP-0014-T02, 2026-08-16): yes.** `flex-auth` may
`tenant.guardrail.read` and may not `tenant.guardrail.set`.
`tenant-engine` may do both. Nobody else may do either.

Reasoning:

1. **The second subject exists and is named.** TEN-WP-0006 split the
   actions so "policy can grant you [flex-auth] the read without granting
   anything the write." Their own HTTP tests call the read as
   `actor=flex-auth`. Leaving both actions on the single `tenant-engine`
   subject would keep the seam unused and leave the intended reader
   failing `unknown_subject`.
2. **This is a real difference, not a named no-op.** Unlike
   FLEX-WP-0010-T02, there is a second service identity to distinguish
   from, and a check the reader can fail (`tenant.guardrail.set` as
   `flex-auth` → `action_not_granted`).
3. **Do not invent an `ops` write subject.** Production writes already
   authorize only the `tenant-engine` service identity. Guardrail
   mutations stay on that same identity. Adding `ops` would widen the
   write set without a registered operator.
4. **Do not grant flex-auth any mutate action.** A PDP that can raise a
   ceiling is no longer only a decision maker.

**Revisit when** a second human/operator subject is registered, or when
flex-auth itself needs to read as a different subject id than `flex-auth`.

## Rules

```rego
import future.keywords.contains
import future.keywords.if
import future.keywords.in

valid_actions := {
  "tenant.create",
  "tenant.role.grant",
  "tenant.role.revoke",
  "tenant.plan.assign",
  "tenant.update",
  "tenant.retire",
  "tenant.reactivate",
  "tenant.guardrail.read",
  "tenant.guardrail.set",
}

read_actions := {"tenant.guardrail.read"}

mutate_actions := valid_actions - read_actions

known_subjects := {"tenant-engine", "flex-auth"}

read_subjects := {"tenant-engine", "flex-auth"}

mutate_subjects := {"tenant-engine"}

decision := {"effect": "allow", "reason": "write_api_policy_matched"} if {
  allowed
} else := {"effect": "deny", "reason": first_denial} if {
  true
}

allowed if {
  input.resource.system == "tenant-engine"
  input.action in read_actions
  input.subject.type == "service"
  input.subject.id in read_subjects
}

allowed if {
  input.resource.system == "tenant-engine"
  input.action in mutate_actions
  input.subject.type == "service"
  input.subject.id in mutate_subjects
}

default first_denial := "no_matching_rule"

first_denial := "wrong_system" if {
  input.resource.system != "tenant-engine"
} else := "unknown_action" if {
  not input.action in valid_actions
} else := "wrong_subject_type" if {
  input.subject.type != "service"
} else := "unknown_subject" if {
  not input.subject.id in known_subjects
} else := "action_not_granted" if {
  input.subject.id in known_subjects
}
```

## Tests

```rego test
package flexauth.tenant_engine.write_api_test

import future.keywords.if
import data.flexauth.tenant_engine.write_api

base_request := {
  "id": "check:tenant-engine-create",
  "tenant": "tenant:friendly:binky",
  "subject": {"id": "tenant-engine", "type": "service"},
  "action": "tenant.create",
  "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
}

test_known_operator_create_allowed if {
  write_api.decision.effect == "allow" with input as base_request
}

test_role_grant_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.role.grant",
    "resource": {"id": "t-1", "type": "role-grant", "system": "tenant-engine"}
  }
}

test_tenant_update_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.update",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_tenant_retire_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.retire",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_tenant_reactivate_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.reactivate",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_misspelled_lifecycle_action_denied if {
  write_api.decision.reason == "unknown_action" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.retired",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_unknown_subject_retire_denied if {
  write_api.decision.reason == "unknown_subject" with input as {
    "subject": {"id": "some-other-service", "type": "service"},
    "action": "tenant.retire",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_unknown_subject_denied if {
  write_api.decision.reason == "unknown_subject" with input as {
    "subject": {"id": "some-other-service", "type": "service"},
    "action": "tenant.create",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_wrong_system_denied if {
  write_api.decision.reason == "wrong_system" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.create",
    "resource": {"id": "t-1", "type": "tenant", "system": "some-other-system"}
  }
}

test_unknown_action_denied if {
  write_api.decision.reason == "unknown_action" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.delete",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_wrong_subject_type_denied if {
  write_api.decision.reason == "wrong_subject_type" with input as {
    "subject": {"id": "tenant-engine", "type": "human"},
    "action": "tenant.create",
    "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
  }
}

test_guardrail_read_by_pdp_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "flex-auth", "type": "service"},
    "action": "tenant.guardrail.read",
    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
  }
}

test_guardrail_read_by_writer_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.guardrail.read",
    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
  }
}

test_guardrail_set_by_writer_allowed if {
  write_api.decision.effect == "allow" with input as {
    "subject": {"id": "tenant-engine", "type": "service"},
    "action": "tenant.guardrail.set",
    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
  }
}

test_guardrail_set_by_pdp_denied if {
  write_api.decision.reason == "action_not_granted" with input as {
    "subject": {"id": "flex-auth", "type": "service"},
    "action": "tenant.guardrail.set",
    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
  }
}

test_guardrail_read_unknown_subject_denied if {
  write_api.decision.reason == "unknown_subject" with input as {
    "subject": {"id": "ops", "type": "service"},
    "action": "tenant.guardrail.read",
    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
  }
}

test_misspelled_guardrail_action_denied if {
  write_api.decision.reason == "unknown_action" with input as {
    "subject": {"id": "flex-auth", "type": "service"},
    "action": "tenant.guardrail.get",
    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
  }
}
```