Skip to content
LabTether

Permissions

LabTether uses role-based access control (RBAC) with four built-in roles. Local username/password auth is enabled by default; optional OIDC SSO is supported when provider env vars are configured.

Roles

Role Access Level Description
owner Full Reserved break-glass principal. Owner token + bootstrapped admin user. Only one owner exists per instance.
admin Full (except owner-only) Full access to all features including settings, user management, enrollment, and API key management.
operator Read/write Day-to-day operational workflows -- terminal sessions, desktop sessions, alert triage, incident management, connector operations. Cannot change system settings or manage users.
viewer Read-only Dashboards, topology, service inventory, and alert visibility. Cannot start sessions, execute commands, or modify any data.

What each role can do

Action Owner Admin Operator Viewer
View dashboards, nodes, topology Yes Yes Yes Yes
View alerts and incidents Yes Yes Yes Yes
Start terminal sessions Yes Yes Yes No
Start desktop sessions Yes Yes Yes No
Browse and transfer files Yes Yes Yes No
Execute commands (API/MCP) Yes Yes Yes No
Triage alerts (ack/resolve/silence) Yes Yes Yes No
Manage incidents Yes Yes Yes No
Start/stop/restart containers Yes Yes Yes No
Run update plans Yes Yes Yes No
Change system settings Yes Yes No No
Manage enrollment and tokens Yes Yes No No
Manage users and roles Yes Yes No No
Create and revoke API keys Yes Yes No No
Reset admin credentials Yes Yes No No
Owner token (service-mode fallback) Yes No No No

RBAC enforcement

All API endpoints enforce role checks before processing requests:

Scope Required Role
Read-only API methods (GET) Any authenticated role
Mutating API methods (POST, PATCH, PUT, DELETE) operator or higher
Runtime settings changes admin or owner
Enrollment and agent token management admin or owner
User management endpoints admin or owner
Admin password reset admin or owner
Owner token (LABTETHER_OWNER_TOKEN) owner only (superuser fallback for service-mode automation)

OIDC role mapping

When using OIDC SSO, LabTether maps identity provider claims to internal roles.

Setting Default Description
Role claim labtether_role (fallback: groups) JWT claim used for role mapping
Admin claim values admin,owner Claim values that map to LabTether admin role
Operator claim values operator Claim values that map to LabTether operator role
Default role viewer Role assigned when no claim mapping matches
Auto-provisioning enabled Auto-create LabTether users on first successful OIDC login

Configure these via environment variables:

Variable Default
LABTETHER_OIDC_ROLE_CLAIM labtether_role
LABTETHER_OIDC_ADMIN_ROLES admin,owner
LABTETHER_OIDC_OPERATOR_ROLES operator
LABTETHER_OIDC_DEFAULT_ROLE viewer
LABTETHER_OIDC_AUTO_PROVISION true

See Environment Variables for the full list of LABTETHER_OIDC_* variables.

API key permissions

API keys carry their own role and scope, independent of user accounts. When creating an API key:

  • Role determines the maximum access level (same hierarchy as user roles)
  • Scopes limit what the key can do within that role (e.g., assets:read, assets:exec, docker:*)
  • Asset allowlist (optional) restricts the key to specific managed assets

A key with operator role and assets:exec scope can execute commands, but only on assets in its allowlist. See API Keys for full details.

Tip: Follow the principle of least privilege. Create API keys with only the scopes they need, scoped to specific assets when possible. Use viewer-role keys for dashboards and monitoring integrations.