Roles & Permissions (RBAC)

Nexus GSLB uses role-based access control (RBAC). Each user is assigned a single role; each role carries a set of permission atoms that gate individual API endpoints.

The system API key (GSLB_API_KEY) is always treated as a super-admin and bypasses RBAC entirely.

Built-in Roles

Three system roles are seeded on startup and cannot be deleted (but their permission sets can be updated).

Built-in permission sets

Permission Atoms

Role matrix (complete)

Custom Roles

License: Creating and modifying custom roles requires the enterprise tier. The three built-in roles (tenant_admin, operator, viewer) are available on all tiers. Contact licensing@gslb.nexus to upgrade.

You can create custom roles with any combination of permissions.

WebUI

Admin → Roles → New Role

gslbctl

gslbctl roles create --name "dns-operator" \
  --permissions "domain:read,domain:write,txt:read,txt:write,tsig:read,tsig:write" \
  --server https://nexus.example.com:8880

API

# Create a custom role
POST /api/v1/roles
{
  "name": "dns-operator",
  "permissions": ["domain:read","domain:write","txt:read","txt:write"]
}

# Update a role's permissions
PUT /api/v1/roles/{id}
{
  "permissions": ["domain:read","domain:write"]
}

# Delete a custom role (system roles cannot be deleted)
DELETE /api/v1/roles/{id}

Terraform

resource "nexus_role" "dns_operator" {
  name        = "dns-operator"
  permissions = ["domain:read", "domain:write", "txt:read", "txt:write"]
}

Assigning Roles to Users

A user's role is set at creation time and can be changed via update.

# Create a user with a specific role
POST /api/v1/users
{
  "email": "alice@example.com",
  "password": "...",
  "role": "operator"
}

# Update role
PUT /api/v1/users/{id}
{
  "role": "tenant_admin"
}

In the WebUI: Admin → Users → select user → change role.

RBAC Notes

• The system_admin identity (GSLB_API_KEY) is not a role — it bypasses all permission checks.
• Built-in role permissions are automatically expanded on binary upgrades to include any newly-added permission atoms, without removing admin-added custom permissions.
• Custom roles survive binary upgrades unchanged.
• There is no permission inheritance — a user has exactly the permissions of their assigned role.