# Authorization Architecture

## Two Axes

1. **Identity / role** — who is the actor?
2. **Entitlement / feature** — what is the tenant allowed to use on their plan?

Both must pass for protected business actions.

## Platform & Workspace Roles (Core)

| Role | Scope |
| --- | --- |
| `platform_admin` | Cross-tenant platform administration (bypass workspace role checks) |
| `tenant_owner` | Full workspace control; required for complete onboarding |
| `tenant_admin` | Manage branding/domain/members (as implemented) |
| `tenant_editor` | Content/edit capabilities |
| `tenant_viewer` | Read-only |

Source of truth: `core_platform_db.tenant_memberships` ([ADR-007](adr/ADR-007.md)).

## Identity-Layer Roles

`identity_access_db.tenant_memberships` uses simpler roles (`tenant_admin` / `tenant_member`) for SSO listing — not operational authz.

## Entitlement

Feature keys: `{service_key}.{resource}.{action}`  
Example: `accounting.invoice.create`

Check: `POST /api/v1/tenants/{tenant_id}/features/check`  
Cached in Redis; custom tenant overrides beat plan defaults.

## API Guards (Core)

Configurable `AUTH_REQUIRED`. Dependencies such as `require_authenticated`, `require_platform_admin`, `require_tenant_admin`, `MembershipService.ensure_role`.

## Future

Custom permission trees, invites, and finer RBAC are planned — track in [module-registry.md](../module-registry.md) and [roadmap.md](../roadmap.md).

## Related Documents

- [Identity Architecture](identity-architecture.md)
- [Multi-Tenant Architecture](multi-tenant-architecture.md)
- [Project Principles](../development/project-principles.md)