NEXUS AI RBAC Deep Dive

RBAC deep dive: roles, scopes, and least privilege

Published: August 15, 2026

Category: Security · Platform

Reading time: 14 minutes

Author: NEXUS AI Team

A developer leaves the company on Friday. By Monday, their credentials still open three production deployments, two billing pages, and a secrets vault they haven't touched in four months.

That's not a people problem. That's an access model problem.

Role-Based Access Control (RBAC) is how NEXUS AI answers the question every engineering org eventually asks: who can do what, to which resources, and how do we prove it? This post goes deep the role hierarchy, how scopes layer on top of roles, how least privilege works in practice, and how to design an access model your team will actually maintain.

Why RBAC matters more as your team scales

When it's just you, every door being open is convenient. When you have a team of 12 across three environments, every door being open is a liability.

The breach surface for a SaaS product running on cloud infrastructure is rarely the infrastructure itself. It's the humans and automated systems that have standing access to it:

• A contractor with admin access granted for a two week engagement and never revoked.
• A CI/CD token with full secrets:write permission because it was "easier to set up that way."
• A junior developer who can redeploy production because the staging role got copy-pasted.

NEXUS AI's RBAC system is designed to make the right permission easy to grant and hard to accidentally expand. Least privilege is the default, not a setting you have to configure.

The role hierarchy

NEXUS AI defines four built-in roles. They are ordered by permission level each role is a strict superset of the one below it.

One organization has exactly one Owner. Ownership can be transferred, but not duplicated. This prevents the "everyone is an Owner" pattern that makes incident response a guessing game.

Viewer

Viewers can observe nothing more.

✓ View deployment status (running, stopped, failed)
✓ Read build and runtime logs
✓ See deployment metadata (region, container count, uptime)
✓ View audit log summaries
✗ Trigger any action (deploy, redeploy, rollback, stop)
✗ See secret names or values
✗ Create or revoke Access Tokens
✗ Invite or remove team members

Use Viewer for: product managers monitoring deploy status, customer success checking uptime, external auditors reviewing activity logs, read-only access for contractors.

Developer

Developers can act on deployments. They cannot change platform configuration.

✓ Everything Viewer can do
✓ Deploy, redeploy, rollback, stop deployments
✓ View secret names (DATABASE_URL, STRIPE_KEY) never values
✓ Create Access Tokens scoped to deploy:read and deploy:write only
✗ Create, update, or delete secrets
✗ Create tokens with admin or secrets:write scope
✗ Invite or remove organization members
✗ View billing or usage data

A Developer can push code and redeploy. They cannot change the secrets their code reads. The separation is intentional: it means a Developer-level compromise cannot extract production credentials, only trigger a redeploy.

Admin

Admins own the platform configuration for an organization.

✓ Everything Developer can do
✓ Create, update, and delete secrets
✓ Create Access Tokens with any scope
✓ Invite members and assign roles (up to Admin)
✓ View and export audit logs
✓ Manage domains, billing, and usage
✗ Delete the organization
✗ Transfer ownership
✗ Grant Owner role to another member

Limit Admin to people who actually need to configure secrets or onboard team members. In a 10-person startup, that's usually two or three people. In a 100-person company, it's a dedicated platform team.

Owner

The Owner role is structurally different from Admin it's not just "more permissions," it's accountability. Only one member holds it, and it carries the ability to perform irreversible actions.

✓ Everything Admin can do
✓ Delete the organization and all its resources
✓ Transfer ownership to another Admin
✓ Access all historical audit logs (including deleted members)

The Owner should be the person who is accountable for the business not necessarily the most technical. At a startup, that's the founding engineer or CTO. At an enterprise, it's the platform owner or CISO-designated lead.

How scopes work

Roles define what a human can do. Scopes define what a token can do.

When a Developer (or Admin) creates an Access Token, they can grant that token any scope up to but not exceeding their own permissions. A Developer cannot create a token with secrets:write scope, because Developers cannot write secrets directly.

This is scope containment: tokens cannot be a privilege escalation vector.

The full scope table

Scopes compose. A CI token for a deployment pipeline typically needs deploy:write and nothing else. A token for a read-only monitoring integration needs deploy:read and logs:read. An MCP integration for an AI agent doing deployment management might need deploy:read,deploy:write,logs:read.

Creating a precisely scoped token

# CI/CD: deploy-only, expires in 90 days
nexus token create \
  --name "github-actions-prod" \
  --scopes deploy:write \
  --expires 90d

# Monitoring integration: read-only, no expiry (rotate quarterly via calendar)
nexus token create \
  --name "datadog-integration" \
  --scopes deploy:read,logs:read

# AI agent with deployment management access
nexus token create \
  --name "claude-mcp-agent" \
  --scopes deploy:read,deploy:write,logs:read \
  --expires 30d

# Admin token for a one time onboarding script (delete immediately after use)
nexus token create \
  --name "onboarding-script-2026-04-21" \
  --scopes admin \
  --expires 1d

The last example a short-lived admin token for a specific script, destroyed after use is exactly how temporary elevated access should work. No standing privileged access. No "just in case" tokens that accumulate over months.

Least privilege in practice

Least privilege is not a policy you write. It's a discipline you build into your provisioning process. Here's what it looks like in a real NEXUS AI team across three common scenarios.

Scenario 1: Onboarding a new backend engineer

Wrong approach:

New hire → Admin role → "they'll need it eventually"

Right approach:

New hire → Developer role
Week 1: pair with an Admin for any secrets work
Month 3: reassess do they actually need Admin? (usually no)

The Developer role covers 95% of what an active engineer does: deploy, redeploy, check logs, rollback a bad release. Secret creation is rare and can go through an Admin without slowing anyone down.

Scenario 2: Setting up a GitHub Actions pipeline

Wrong approach:

nexus token create --name "github-actions" --scopes admin
# Stored in GitHub secrets as NEXUS_API_KEY

Right approach:

# One token per environment, deploy:write only
nexus token create --name "github-actions-staging" --scopes deploy:write --expires 90d
nexus token create --name "github-actions-prod" --scopes deploy:write --expires 90d

# Store each in the corresponding GitHub environment secret
# github.com/org/repo → Settings → Environments → staging → NEXUS_API_KEY
# github.com/org/repo → Settings → Environments → production → NEXUS_API_KEY

Environment scoped tokens mean a staging pipeline compromise cannot touch production. The deploy:write scope means the pipeline can redeploy but cannot read or modify secrets.

Scenario 3: Granting an external contractor temporary access

Wrong approach:

Contractor → Admin role → "we'll remove it when they're done"
(They're done. It's still there. Six months later: breach.)

Right approach:

# Invite as Viewer they can observe, not act
nexus member invite contractor@agency.com --role Viewer

# If they need to trigger deploys, create a scoped token with explicit expiry
nexus token create \
  --name "contractor-agency-q2-2026" \
  --scopes deploy:write \
  --expires 30d

# Deliver the token via a secure channel. Calendar reminder for 29 days out.
# At project end: revoke the token and remove the member
nexus token revoke tok_01HX9...
nexus member remove contractor@agency.com

The token expires automatically even if you forget. The member removal is still important it cleans up the audit trail and signals a clean handoff.

Resource-level access: deployments and projects

Roles apply at the organization level by default. But NEXUS AI also supports project-scoped membership isolating access to a subset of deployments within an organization.

# Add a Developer to a specific project only
nexus project member add \
  --project payments-service \
  --email engineer@company.com \
  --role Developer

# They can now deploy payments-service/* deployments
# They cannot see auth-service/*, user-service/*, or any other project

Project-scoped access is useful for:

• Regulated workloads — your payments team accesses the payments project; your analytics team accesses the analytics project. No overlap.
• Multi-tenant organizations agencies managing deployments for multiple clients. Each client's project is isolated.
• Contractor access — limit a vendor to exactly the project they're working on.

Organization-level Admins retain visibility across all projects. Project-scoped Developers cannot see outside their project boundary.

RBAC and AI agents

NEXUS AI's 37 MCP tools for Claude and AI agents operate under the same RBAC model as human callers. A token issued to an AI agent carries exactly the same scope enforcement no exceptions.

This matters because AI agents tend to be given more access than they need "because it's easier." An agent with admin scope that goes wrong is a full organization compromise. An agent with deploy:read that goes wrong reveals status information and nothing else.

Designing safe agent access

Read-only diagnostic agent — Claude inspects logs, checks deployment health, surfaces anomalies:

nexus token create \
  --name "claude-diagnostic" \
  --scopes deploy:read,logs:read \
  --expires 7d

The agent cannot deploy, rollback, or change anything. It observes and reports.

Deployment automation agent — Claude reacts to CI signals and triggers redeployments:

nexus token create \
  --name "claude-deploy-agent" \
  --scopes deploy:read,deploy:write,logs:read \
  --expires 30d

The agent can act on deployments. It cannot touch secrets, billing, or team membership.

Incident response agent — Claude triages a production incident, can rollback if needed:

# Short-lived, manually issued during an incident
nexus token create \
  --name "claude-incident-2026-04-21" \
  --scopes deploy:read,deploy:write,logs:read \
  --expires 4h

4-hour expiry. The token disappears when the incident window ends. No standing elevated access for AI agents.

The rule: grant an AI agent the minimum scope it needs to complete its defined task. Then set an expiry that matches the task duration — not "never" because that's convenient.

What RBAC cannot do

Knowing the limits of any security control is as important as knowing what it covers.

RBAC does not protect against a compromised Owner account. The Owner role has full access. If an Owner's credentials are compromised, the attacker has full access. Protect Owner accounts with hardware MFA, not just TOTP.

RBAC does not prevent a Developer from logging sensitive data. If your application logs process.env.DATABASE_URL at startup, that value appears in runtime logs — which Developers can read. Secret management starts with application code discipline.

RBAC does not enforce network-level isolation. A Developer with deploy:write can push a container that opens a reverse shell. Pair RBAC with container security policies and network egress controls for workloads that require it.

RBAC does not replace secrets rotation. Least privilege reduces blast radius when a secret is compromised. Rotation reduces the window of exposure. Both are required for a complete security posture.

The access model audit

Run this quarterly. It takes 20 minutes and it will find something to fix every time.

# List all organization members and their roles
nexus member list

# List all active tokens with creation date and last-used date
nexus token list --show-last-used

# Check for tokens with no expiry
nexus token list --no-expiry

# Check for tokens unused in 30+ days
nexus token list --unused-since 30d

For each token unused in 30+ days: revoke it. For each admin-scoped token that isn't for a one-time script: replace it with narrower scopes. For each member at a role higher than their current responsibilities: downgrade it.

The goal is to reach a state where every active token has a name that explains exactly what it does, an expiry that matches how long it needs to exist, and the minimum scope to do its job.

RBAC and compliance

If you're in a regulated industry healthcare, fintech, legal — RBAC is table stakes for compliance. NEXUS AI's RBAC system maps directly to common control requirements:

Enterprise and Enterprise On-Prem plans include 90-day and indefinite audit log retention respectively. Logs are exportable to Datadog, Grafana, Splunk, or any SIEM via the audit log export API.

Checklist: production-grade RBAC setup

• [ ] Assign roles at the minimum level needed start with Developer, escalate to Admin only when demonstrated necessary
• [ ] No team member should have Owner role unless they're accountable for the organization
• [ ] Every CI/CD pipeline uses a separate deploy:write token per environment
• [ ] Every token has a name that identifies its purpose and a --expires flag
• [ ] No admin-scoped tokens in standing use only for one-time scripts with 1-day expiry
• [ ] AI agent tokens scoped to exactly what the agent does (not admin)
• [ ] Quarterly access review: nexus token list --unused-since 30d and nexus member list
• [ ] Project-scoped membership for workloads that should be isolated (payments, healthcare, multi-client)
• [ ] Owner account protected with hardware MFA (YubiKey or equivalent)
• [ ] Offboarding runbook: member remove + all associated tokens revoke, same day

Frequently asked questions

Can a Developer see their own Access Tokens after creation?

Token values are shown once at creation — never again. A Developer can list their tokens by name and ID (nexus token list --mine), but the token_value is never retrievable. If lost, rotate.

What happens to tokens when a member is removed?

Tokens are scoped to the organization, not to the member who created them. Removing a member does not automatically revoke their tokens. Run nexus token list --created-by email@company.com and revoke manually as part of offboarding. A future release will offer member-removal with automatic token revocation.

Can a Developer escalate their own role?

No. Role changes require Admin or Owner. A Developer cannot call any API endpoint that modifies their own or another member's role.

How does NEXUS AI handle role changes mid-session?

Role and scope changes take effect immediately. An active API session using a token that gets revoked will receive a 401 Unauthorized on the next call — there's no grace window for human sessions (only for the 5-minute deploy token rotation window).

Is there a way to grant time-limited elevated access without creating a token?

Not currently at the role level — role changes are persistent until manually reverted. Use a short-lived admin-scoped token for temporary elevated operations instead of upgrading a member's role. This keeps the audit trail cleaner and eliminates the "I forgot to downgrade them" failure mode.

We're on the Starter plan. Do we get RBAC?

Yes. All four roles and the full scope system ship on every plan, including Starter at $29/mo. Project-scoped membership and audit log export are Enterprise features.

What's next

Access control works best when it's boring when every token has a clear purpose, every role is appropriate, and your quarterly audit finds nothing to clean up. That state is achievable. It requires an initial setup investment of about two hours and 20 minutes of discipline every quarter.

Start with your CI/CD tokens. Replace any admin-scoped pipeline token with deploy:write. That one change eliminates your largest standing access risk.

For regulated workloads, compliance tooling, or teams larger than 20 engineers, the Enterprise plan adds SAML SSO, custom audit log retention, and dedicated security review. Reach out at nexusai.run.

Related reading:

• Stop shipping secrets. Start using a vault.
• MCP integration: 37 tools for Claude and AI agents
• Audit logs and compliance: what gets recorded and why
• How NEXUS AI deploys your app in under 5 minutes

Least privilege is not paranoia. It's the discipline that makes incidents containable.