Roles & Permissions

ByteOr Cloud resolves authorization through organization and project roles, then applies environment-level checks on the resulting operation.

Control-plane reference summary

Cloud is still a guide-first public surface, so this page keeps the central RBAC summary and links back out to the repo-owned Cloud docs for operator workflow detail.

ByteOr Cloud uses role-based access control (RBAC) to govern who can view, modify, and operate resources. Roles are assigned at the organization or project scope and cascade downward through the resource hierarchy.

Roles

Role	Scope	Description
`org_admin`	Organization	Full control over the organization, all projects, and all environments. Can manage memberships and billing.
`project_admin`	Project	Full control over a single project and its environments. Cannot manage organization-level settings.
`operator`	Project	Can create deployments, approve/deny requests, and manage agents. Cannot modify project settings or memberships.
`viewer`	Project	Read-only access to project resources. Cannot trigger any mutations.

Permission Matrix

Each permission maps to one or more API actions. The matrix below shows which roles grant each permission.

Permission	`org_admin`	`project_admin`	`operator`	`viewer`
`ViewOrg`	✅	✅	✅	✅
`ManageOrgMemberships`	✅	—	—	—
`ViewProject`	✅	✅	✅	✅
`ManageProject`	✅	✅	—	—
`OperateProject`	✅	✅	✅	—
`ViewEnvironment`	✅	✅	✅	✅
`ManageEnvironment`	✅	✅	—	—
`OperateEnvironment`	✅	✅	✅	—

Role Resolution Rules

When a user has roles at multiple scopes, the following rules determine effective permissions:

org_admin override — An org_admin implicitly holds every permission on every project and environment within the organization. No additional role assignments are needed.
Project-level fallback — If a user has no project-specific role, the system checks for an organization-level role. A viewer role at the org level grants ViewProject and ViewEnvironment across all projects.
Nested scope enforcement — Permissions required for a resource at the environment level also require the corresponding view permission at the project and organization level. For example, OperateEnvironment requires ViewProject on the parent project.

Audit Events

Every authorization decision and identity event is recorded in the audit log. Each entry includes the fields: outcome, actor, resource_scope, and timestamp.

Event Kind	Description
`LoginStarted`	OAuth login flow initiated.
`LoginCompleted`	User successfully authenticated and a session was issued.
`LoginFailed`	Authentication failed (invalid code, expired state, provider error).
`MembershipChanged`	A role assignment was created, updated, or removed.
`ApiKeyIssued`	A new agent API key was generated during enrollment.
`ApiKeyRevoked`	An agent API key was revoked by an administrator.
`ApiKeyAuthenticated`	An agent authenticated successfully using its API key.
`ActionAuthorized`	A permission check passed and the requested action was allowed.
`PermissionDenied`	A permission check failed and the request was rejected with `403`.