# tenant-engine Action Vocabulary

This document defines the action vocabulary for `tenant-engine` as a
flex-auth protected system (`FLEX-WP-0008-T01`). Action names here match
`tenant-engine`'s own `authz.FlexAuthWriteAuthorizer` mapping exactly
(`tenant_engine/src/tenant_engine/authz.py`) — coordinated between the two
repos, not independently invented.

| Action | tenant-engine write endpoint | Resource type | Decision effects |
| --- | --- | --- | --- |
| `tenant.create` | `POST /tenants` | `tenant` | `allow`, `deny` |
| `tenant.role.grant` | `POST /tenants/{id}/roles/grant` | `role-grant` | `allow`, `deny` |
| `tenant.role.revoke` | `POST /tenants/{id}/roles/revoke` | `role-grant` | `allow`, `deny` |
| `tenant.plan.assign` | `POST /tenants/{id}/plan` | `plan-assignment` | `allow`, `deny` |
| `tenant.update` | `PATCH /tenants/{id}` | `tenant` | `allow`, `deny` |
| `tenant.retire` | `POST /tenants/{id}/retire` | `tenant` | `allow`, `deny` |
| `tenant.reactivate` | `POST /tenants/{id}/reactivate` | `tenant` | `allow`, `deny` |

The last three are the tenant lifecycle actions added by `FLEX-WP-0010` for
`TEN-WP-0005`. They are three actions rather than one `tenant.write` because
tenant-engine separated them so policy *can* permit renaming a tenant without
thereby permitting retiring it. Under the current single-operator model all
three resolve identically — the separation is a seam for later, and the
reasoning for not yet treating `tenant.retire` more strictly is recorded in
`examples/tenant-engine/policy_package.md`.

These are the only seven actions `tenant-engine` sends to `POST /v1/check` —
its `FlexAuthCheckClient` (`TEN-WP-0003`) never sends anything else, and
`tenant-engine`'s reads (`/roles`, `/roles/live`) are never gated through
flex-auth at all; they're `tenant-engine`'s own cache-read and live-lookup
endpoints, consumed *by* `key-cape` and `flex-auth` respectively.

## Not in scope for this vocabulary

`tenant-engine`'s capability roles (`PLTF`/`IAM`/`VEN`/`CUS`, ADR-0014) are
**tenant** state — what a tenant is allowed to do on the platform. This
vocabulary governs a different question: which **operator/service
subjects** are allowed to call `tenant-engine`'s admin API at all. The
lifecycle actions do not change that boundary: `tenant.retire` asks whether
*this caller* may retire a tenant, not what a *retired tenant* may still do —
the latter is tenant state that tenant-engine enforces itself. The two
must not be conflated — a policy package that checked a *caller's* action
against a *tenant's* capability roles would be checking the wrong thing.
See `examples/tenant-engine/policy_package.md`'s Rules section for how the
distinction is enforced.

## Related

- `docs/tenant-engine-resource-namespace.md`
- `examples/tenant-engine/`