Realms

Realms are organizational containers in PrivateAIM Hub that group identity providers, robots, users, roles, and nodes. They are managed through Authup and enforced across all Hub services.

Overview

Each realm is an isolated organizational unit. Resources created within a realm (projects, analyses, nodes) are scoped to that realm unless accessed by a master realm administrator.

• The master realm has global access — its members can manage all resources across realms
• Non-master realm users can only access resources within their own realm

Managing Realms

Creating a Realm

Realm Details

Realm Scoping

All realm-scoped entities carry a realm_id column. Access is enforced by the isRealmResourceWritable() helper in every entity service:

Master realm member  →  can read/write all resources
Other realm member   →  can only read/write own realm's resources

This applies to all CRUD operations — creating, reading, updating, and deleting entities.

Users

Users are human accounts within a realm. Administrators can manage users, assign roles, and view details.

Robots

Robots are API pseudo-users for automation. They belong to a realm and are assigned roles and permissions just like human users.

Use robots for:

• Automated pipelines that interact with the Hub API
• Service-to-service communication
• CI/CD integrations

Roles & Permissions

Hub uses role-based access control (RBAC) via Authup:

• Roles group related permissions and are assigned to users or robots within a realm
• Permissions are pre-defined actions (e.g., node_create, analysis_update) checked at the service layer
• Two-phase permission model: preCheck (fast fail) then check (with policy attributes)

Identity Providers

Each realm can configure OIDC identity providers for federated authentication. Users authenticate through their realm's identity provider, and Authup maps the external identity to a Hub user.