User Roles & Permissions Explained

RUAL does not use fixed roles — access is composed from per-user permission settings, scopes, and optional user groups. Learn how the pieces map to administrators, developers, API users, and visitors.

The Access Model

If you come from a system with fixed roles like "admin" or "editor", RUAL works differently: there are no predefined roles. Instead, what a user can do is composed from three layers on their user document:

• Permissions and settings — named switches such as Staging Developer or is_root_user that control what the account may do in RUAL Studio and through cluster APIs.
• Scopes — values in the custom_scopes array that grant access to specific pages and APIs built on the cluster.
• User groups — reusable bundles of scopes, assigned through the groups_guid array, that act like role templates.

Mapped to the classic role mental model:

• Cluster administrators hold the Cluster Admin permission and the is_root_user setting. In the All users list they are marked with a * (star) and possess full access to all resources within the cluster.
• Developers hold blueprint permissions — Wildcard Scope to create new resources, plus Staging Developer or Production Developer depending on how far they may go.
• API-only users have an account but never open RUAL Studio. They authenticate through the login APIs and their scopes decide which pages and APIs they can call.
• Visitors have no account at all. They only reach content in the *public scope; anything scoped differently redirects them to the login or forbidden page.

Permission Levels Guide

These are the permissions and settings you will assign most often. The full list of fifteen permissions is documented in User Access Management.

Finer-grained blueprint permissions — Blueprints: All Access, Blueprints: Activate Blueprints, Blueprints: Remove Blueprints, and Blueprints: Deploy Blueprints — let you tune exactly how far each developer may go. Cluster APIs use the same model with scope values such as setting_manage_users and setting_edit_blueprints.

RUAL Studio Access vs API Access

There are two distinct ways to work with a cluster, controlled separately:

API tokens are valid for 14 days and extended automatically while actively used. Pass a token as an Authorization: Bearer header, as x-authtoken or x-token, as a cookie named access_token, or in the URL as ?access_token=. See Getting Access for the onboarding flow and Cluster APIs for the authentication reference.

For API access, the custom_scopes array on the user document is decisive: every page and API you build is protected by scopes, and a token only reaches the endpoints its user's scopes cover. An account with the scopes below can call pages and APIs scoped view_customers or create_orders, and nothing else:

{
  "custom_scopes": [
    "view_customers",
    "create_orders"
  ],
  "username": "jane.doe"
}

User Groups as Role Templates

User groups are the closest thing RUAL has to roles. A group is a document in the usergroups database with a name and a scope array. Assign a user to a group by adding the group's guid to the groups_guid array on the user document — from then on, the user receives every scope in that group. A user can belong to multiple groups and receives all unique scopes from all of them, plus any individual scopes in their own custom_scopes.

Model your groups after the kinds of users your cluster serves:

Visitors need no group — without an account they only see *public content. A user assigned to two groups looks like this:

{
  "custom_scopes": [],
  "groups_guid": [
    "94ad734891564818888bea7e2519aedd",
    "1c5bfaf8fb034f8498d204c5072b554e"
  ],
  "username": "jane.doe"
}

Setting Up Team Member Access

1. Sign in to RUAL Studio with an administrator account and open the All users section from the left-side menu.
2. Create the user with a username and password, and share the cluster URL and credentials privately.
3. Assign the permissions the work requires — for a developer, start with Staging Developer and add more only when needed.
4. Add any individual scopes to custom_scopes, or better: assign the user to a group via groups_guid so permissions follow the role, not the person.
5. Have the user sign in and complete first-time setup, including two-factor authentication when your cluster requires it.

Security Best Practices

• Least privilege: grant only the scopes and permissions a user needs, preferably through user groups instead of individual scopes.
• Protect root accounts: is_root_user accounts get extra protection against login attacks and password forget requests — keep them few, and never enable allow_login_as_user for them (RUAL prevents this).
• Guard system settings: the Manage System Settings permission controls who can view and change system settings; access to secured system settings is logged.
• Review the audit log: sensitive actions such as removing blueprints and changing permissions are recorded — review the log regularly.
• Use two-factor authentication: users manage their active sessions and multi-factor options on the default security page.

RUAL also blocks mass multi-authentication attempts from the same IP address and repeated unsuccessful attempts against the same account by default.

Next Steps

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem