Roles and permissions
Understand how organization roles, workspace roles, and service accounts control access to Blue Guardrails.
Blue Guardrails uses a two-level role-based access control system. Organizations contain workspaces, and each level has its own roles and permissions.
Every user belongs to an organization with an organization role. When you add them to a workspace, they get a separate workspace role. The two roles are independent. A user can be an organization Viewer but a workspace Admin, or vice versa.
Workspaces also support service accounts. A service account is a non-human principal that authenticates with API keys and holds a custom subset of workspace permissions.
Organization roles
Organization roles control who can manage members, manage billing, update organization settings, and create workspaces.
| Role | Description |
|---|---|
| Super Admin | Full access to everything in the organization. Can assign any role, manage members, manage billing, update settings, create workspaces, and recover access to orphaned workspaces. |
| Admin | Can manage organization members and create workspaces. Can't access billing, change organization settings, or assign the Super Admin role. |
| Billing Manager | Can view the organization and manage billing (spend, balance, history). Can't manage members or create workspaces. |
| Contributor | Can view the organization and create workspaces. Can't manage members or billing. |
| Viewer | Can view the organization. Can't create workspaces, manage members, or access billing. |
Organization permissions matrix
| Permission | Super Admin | Admin | Billing Manager | Contributor | Viewer |
|---|---|---|---|---|---|
| View organization | Yes | Yes | Yes | Yes | Yes |
| Manage members | Yes | Yes | |||
| Manage billing | Yes | Yes | |||
| Update organization settings | Yes | ||||
| Create workspaces | Yes | Yes | Yes | ||
| Recover orphaned workspaces | Yes |
Role assignment rules
Not every role can assign every other role:
- Super Admin can assign any role, including Super Admin.
- Admin can assign Admin, Billing Manager, Contributor, and Viewer. Not Super Admin.
- Other roles can't assign roles.
The same rules apply when changing an existing member's role.
Safety policy
An organization must always have at least one Super Admin. Blue Guardrails prevents removing or demoting the last Super Admin.
Workspace roles
Workspace roles control what a member can do inside a single workspace. Each workspace keeps its own member list and role assignments.
| Role | Description |
|---|---|
| Admin | Full workspace access. Manages members, service accounts, settings, and workspace deletion, on top of everything a Contributor can do. |
| Contributor | Can read data, send traces, run evaluations and experiments, manage evaluators and labels, and create service accounts. Can't change settings, manage members, or manage existing service accounts. |
| Viewer | Can read workspace data and view members. Can't write data, run evaluations, or change anything. |
Workspace permissions matrix
Each role grants a fixed set of fine-grained permissions:
| Permission | Admin | Contributor | Viewer |
|---|---|---|---|
| Read data (traces, experiments, configs) | Yes | Yes | Yes |
| Write traces | Yes | Yes | |
| Run evaluations | Yes | Yes | |
| Run experiments | Yes | Yes | |
| Delete experiments | Yes | Yes | |
| Manage evaluators | Yes | Yes | |
| Manage labels | Yes | Yes | |
| Run agent | Yes | Yes | |
| Create service accounts | Yes | Yes | |
| Manage service accounts | Yes | ||
| View members | Yes | Yes | Yes |
| Manage members | Yes | ||
| Update workspace settings | Yes | ||
| Delete workspace | Yes |
Safety policy
A workspace must always have at least one Admin. Blue Guardrails prevents removing or demoting the last Admin.
Service accounts
Service accounts are non-human principals scoped to a workspace. Use them for automated traffic such as trace ingestion from your application, CI jobs that run experiments, or batch evaluators.
A service account holds a custom set of workspace permissions. You authenticate as the service account by sending one of its API keys in the Authorization header.
Grantable permissions
Only a subset of workspace permissions can be granted to service accounts:
- Read data
- Write traces
- Run evaluations
- Run experiments
- Delete experiments
Permissions that involve human judgement or workspace governance stay session-only. A service account can never hold them, even if its creator can. This includes managing evaluators, labeling, running the agent, managing members, and changing settings.
Creating and managing service accounts
Workspace Contributors and Admins can create service accounts. Only workspace Admins can manage existing service accounts (rename, change permissions, disable, rotate keys).
When you create or update a service account, you can only grant permissions you currently hold yourself. There are no implicit grants. Each permission must be selected explicitly.
API keys
API keys are credentials for service accounts. Each key has its own expiry (up to 365 days) and can be revoked independently.
When a request authenticates with an API key, Blue Guardrails resolves the service account and applies its permissions for that request only. The key never inherits permissions from the user who created it.
For step-by-step instructions, see Manage your workspaces.
Recovering an orphaned workspace
A workspace can end up with no available admin, for example when the last admin leaves the organization. Blue Guardrails handles this through an explicit recovery endpoint.
Anyone with the org-level Recover orphaned workspaces permission (Super Admin by default) can call POST /v1/workspaces/{workspace_id}/recover-membership to mint a workspace membership for themselves or another user. They choose the new member's role; it defaults to Admin.
Recovery is the only path that lets an organization role grant workspace access. To do anything else inside a workspace, you need a workspace role or a valid service-account API key.
Default roles
When you invite someone to an organization without choosing a role, they get the Viewer role. When you invite someone to a workspace without choosing a role, they get the Contributor role.