Permissions¶

Totis uses a role-based access control (RBAC) system to manage user permissions within workspaces.

Workspace Roles¶

Each workspace member is assigned one of the following roles:

Role	Description
`OWNER`	Full control including billing and deletion
`ADMIN`	Manage workspace settings and members
`DEVELOPER`	Create and manage builds
`VIEWER`	Read-only access

Permission Matrix¶

Workspace Permissions¶

Permission	Owner	Admin	Developer	Viewer
`WORKSPACE_READ`	X	X	X	X
`WORKSPACE_EDIT`	X	X
`WORKSPACE_DELETE`	X

Project Permissions¶

Permission	Owner	Admin	Developer	Viewer
`PROJECT_READ`	X	X	X	X
`PROJECT_CREATE`	X	X	X
`PROJECT_EDIT`	X	X	X
`PROJECT_DELETE`	X	X

Build Permissions¶

Permission	Owner	Admin	Developer	Viewer
`BUILD_CREATE`	X	X	X
`BUILD_EDIT`	X	X	X
`BUILD_DELETE`	X	X	X
`BUILD_UPLOAD`	X	X	X
`BUILD_DOWNLOAD`	X	X	X	X
`BUILD_CREATE_LINKS`	X	X	X

Permission Hierarchy¶

Roles are hierarchical, with each level inheriting permissions from lower levels:

OWNER
  └── ADMIN
       └── DEVELOPER
            └── VIEWER

Permission Definitions¶

Workspace Level¶

Permission	Description
`WORKSPACE_READ`	View workspace details and members
`WORKSPACE_EDIT`	Update workspace settings, invite/remove members
`WORKSPACE_DELETE`	Delete the workspace

Project Level¶

Permission	Description
`PROJECT_READ`	View project and its builds
`PROJECT_CREATE`	Create new projects
`PROJECT_EDIT`	Update project settings
`PROJECT_DELETE`	Delete projects

Build Level¶

Permission	Description
`BUILD_CREATE`	Create new builds
`BUILD_EDIT`	Update build metadata
`BUILD_DELETE`	Delete builds and files
`BUILD_UPLOAD`	Upload files to builds
`BUILD_DOWNLOAD`	Download build files
`BUILD_CREATE_LINKS`	Create public sharing links

Checking Permissions¶

In API Responses¶

Workspace and project responses include the user's permissions:

{
  "workspaceId": "ws123",
  "name": "My Company",
  "permissions": [
    "WORKSPACE_READ",
    "WORKSPACE_EDIT",
    "PROJECT_CREATE",
    "PROJECT_READ",
    "PROJECT_EDIT",
    "BUILD_CREATE",
    "BUILD_UPLOAD",
    "BUILD_DOWNLOAD",
    "BUILD_CREATE_LINKS"
  ]
}

Before Making Requests¶

Check if the user has required permissions before attempting operations:

// Check if user can create builds
const workspace = await getWorkspace('my-company');
const canCreateBuild = workspace.permissions.includes('BUILD_CREATE');

if (canCreateBuild) {
  await createBuild(buildData);
} else {
  showError('You do not have permission to create builds');
}

Role Assignment¶

At Workspace Creation¶

The user who creates a workspace automatically becomes the OWNER.

When Inviting Users¶

Specify the role when inviting:

{
  "email": "[email protected]",
  "role": "DEVELOPER"
}

Updating Roles¶

Owners and Admins can update member roles:

{
  "workspaceRole": "ADMIN"
}

Role Restrictions

Owners cannot be demoted
Users cannot change their own role
Only Owners, Admins, and Developers can update roles

Special Permissions¶

Owner-Only Actions¶

Some actions require the OWNER role specifically:

Manage billing and subscriptions
Delete the workspace
Transfer ownership

Billing Management¶

Payment-related endpoints additionally check for OWNER role:

private void validateOwnerAccess(String workspaceSlug) {
    var member = workspaceMemberRepository.findByWorkspaceIdAndUserId(...);
    if (member.getRole() != WorkspaceRole.OWNER) {
        throw new ApplicationException(ErrorType.FORBIDDEN,
            "Only workspace owners can manage billing.");
    }
}

Error Responses¶

Status	Error	Description
401	`UNAUTHORIZED`	Not authenticated
403	`FORBIDDEN`	Authenticated but lacks permission
403	`WORKSPACE_UNAUTHORIZED`	Not a member of the workspace

Best Practices¶

Check permissions client-side: Use the permissions array to show/hide UI elements
Handle 403 gracefully: Provide meaningful feedback to users
Use minimal permissions: Assign the lowest role that meets requirements
Regular audits: Review workspace members and their roles periodically