RBAC Roles & Environment Promotion

Overview

This page covers two related topics for teams running Sulus at enterprise scale: the three Role-Based Access Control (RBAC) roles available within an organization, and the recommended pattern for isolating dev/uat/prod environments and promoting configuration changes between them declaratively, through CI/CD, rather than editing production directly. For the basic invite workflow and SSO setup, see Team Management & SSO and Team Invitations & Roles — this page goes deeper into the RBAC role table plus the enterprise environment-promotion workflow that those pages only summarize.

Sulus uses Role-Based Access Control (RBAC) to manage what each member of an organization can do. A role is assigned when a member is invited, and it governs both dashboard and API access:

These three roles are the same across every organization — there are no custom or granular permission sets. See Team Management & SSO for how roles interact with single sign-on.

For teams running multiple environments — typically dev, uat, and prod — the recommended enterprise pattern is to use a separate Sulus organization per environment (for example acme-dev, acme-uat, acme-prod) rather than a single shared organization with environment tags. This gives you strict data and access isolation between environments:

• Dev — open to engineers, safe for synthetic or scrubbed test data
• Uat — open to QA and subject-matter experts, ideally production-like data with real customer PII avoided where possible
• Prod — restricted to a small set of operators, real data, strict logging and audit, and changes made only through CI/CD — never direct dashboard edits

Once environments are split into separate organizations, apply least-privilege RBAC across them:

• Developers — write access to dev, read-only access to uat, and no direct write access to prod
• CI/CD service principal — one dedicated Admin-level API key per organization, used only by your automated pipeline, never by a human directly
• Production changes — applied only via CI/CD using the prod service principal, so every production change has an associated pipeline run and audit trail

The resources typically promoted declaratively from dev → uat → prod are:

• Assistants (system prompt, model, voice, transcriber configuration)
• Squads (member structure and handoff routing)
• Tools and integrations (function tools, API request tools, credentials referenced by ID)
• Knowledge bases (uploaded files and query tool configuration)
• Runtime and policy settings (timeouts, fallback plans, compliance and consent settings)

Storing each of these as JSON/YAML configuration in Git — "config as code" — is what makes promotion between environments repeatable and auditable, rather than a manual, error-prone re-creation of settings in each org.

A typical promotion flow looks like this:

1. Develop in dev — create or modify configuration in Git, run validation/lint checks, apply to the dev organization, and run your own tests against it
2. Promote to uat — open a pull request; your CI pipeline runs a plan against uat and posts the diff for review; on approval, CI applies the change using the uat service principal
3. Promote to prod — CI runs a plan against prod and requires reviewer/owner approval before applying; the apply is executed with the prod service principal and the change set is recorded
4. Rollback — because every applied state corresponds to a Git commit, rolling back is a Git revert; CI re-applies the previous configuration idempotently

A CI/CD pipeline (for example, using GitHub Actions or GitLab CI) typically has a plan step and a gated apply step per environment:

jobs:
  plan:
    steps:
      - run: npm run validate:all
      - name: Plan UAT
        env:
          ORG_ID: ${{ secrets.UAT_ORG_ID }}
          API_TOKEN: ${{ secrets.UAT_TOKEN }}
        run: npm run plan -- --env uat --out plan-uat.txt

  deploy-prod:
    if: github.ref == 'refs/heads/main'
    needs: [ plan ]
    environment:
      name: prod
    steps:
      - name: Apply PROD
        env:
          ORG_ID: ${{ secrets.PROD_ORG_ID }}
          API_TOKEN: ${{ secrets.PROD_TOKEN }}
        run: npm run apply -- --env prod --approve

Secrets management guidance:

• Never commit secrets (API keys, credential values) to your repository — reference them via your CI platform's secret store or a dedicated secret manager (e.g., Vault, AWS Secrets Manager, or Google Cloud Secret Manager)
• Use a separate set of secrets per environment — a dev API key should never be reused in uat or prod
• Rotate secrets on a regular schedule, and immediately after any suspected exposure

Before promoting a change to prod, verify:

• Configuration has been validated and peer-reviewed
• Required secrets already exist in the target environment
• The plan diff shows only the expected changes, with no unmanaged drift
• UAT sign-off has been recorded
• Any required change ticket and reviewer approvals are complete
• Current prod state has been exported as a backup before applying
• Alerting is in place for error rate and tool-call failures after the change goes live

In summary: isolate environments as separate organizations, apply least-privilege RBAC per environment, store configuration as code, and promote only through a reviewed, auditable CI/CD pipeline — with a Git revert as your rollback path.