Authorization Controls
Role and capability boundaries for DevDocs publishing operations.
Authorization controls define who can change a docs site and which actions require stronger trust.
Role defaults
| Role | Default capability |
|---|---|
| Reader | View public docs and public API references |
| Contributor | Open previews and inspect build output |
| Reviewer | Approve content and release-readiness checks |
| Admin | Manage sources, domains, auth policy, and production promotion |
| Service | Execute scoped automation with least-privilege tokens |
High-risk actions
The following actions should require admin or service-level authority:
- promoting a release to production
- changing a production domain target
- adding or removing an origin allowlist entry
- storing or rotating service credentials
- enabling playground execution for external APIs
- changing organization-level auth policy
API playground controls
The playground needs its own authorization layer because it can send requests outside the docs app:
- public readers can inspect endpoint docs and examples
- signed-in users can run safe demo requests
- organization members can use approved environments
- admins approve external origins, proxy behavior, and persisted environment metadata
Implementation expectation
Every protected action should record an audit event with actor, organization, target resource, action, and result. The audit trail is part of the product, not an internal afterthought.