flex-auth/docs/tenant-engine-action-vocabulary.md

# 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` |

These are the only four 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 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/`
FLEX-WP-0008 T01-T02: tenant-engine resource/action vocabulary + policy package docs/tenant-engine-{resource-namespace,action-vocabulary}.md: four actions (tenant.create, tenant.role.grant, tenant.role.revoke, tenant.plan.assign) matching tenant_engine/src/tenant_engine/authz.py's _RESOURCE_TYPES mapping exactly. No resource_manifest.yaml -- tenant-engine's resources are created dynamically, unlike ops-warden's fixed SSH-certificate inventory; documented as a deliberate deviation. examples/tenant-engine/: protected_system_manifest.yaml, subject_manifest.yaml (one registered caller: tenant-engine's own service identity), policy_package.md (Rego rules + embedded tests), policy_fixtures.yaml (8 allow/deny pairs), assembled registry_snapshot.json, two standalone check_request examples, README. Design decision made explicit in the workplan: operator/service-identity authorization (one known subject, four known actions), not aal2+assurance + tenant-capability-role checking -- CheckRequest carries no assurance claim yet (TEN-WP-0003 already flagged actor as a plain request-body field, not a real auth context), and a tenant's capability roles are the tenant's own state, not a property of who may call tenant-engine's admin API. Revisit once KEY-WP-0005 gives callers a real assurance-bearing identity. Verified for real: built ./cmd/flex-auth, ran test-policy (6 tests + 8 fixtures, all pass), load-registry, check against both example requests. Then ran a live flex-auth serve with this exact registry+policy and pointed tenant-engine's real, unmodified FlexAuthCheckClient/FlexAuthWriteAuthorizer at it over real HTTP: unknown subject -> 403, tenant-engine -> 201. go test ./... still green across the whole repo. T03 (live-lookup context adapter for other protected systems) stays open -- new Go adapter package, tracked separately. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> 2026-07-23 23:05:57 +02:00			`# 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` \|

			These are the only four 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 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/`