Role-Based Access Control

Implement security and access management for Builder applications with RBAC

The foundation is governed by design, and RBAC is how that governance reaches into each workspace. Role-Based Access Control (RBAC) is the security model used in Prisme.ai to manage who can access, modify, and use different parts of your workspace. It ensures that users only have the permissions they need while protecting sensitive information and functionality.

RBAC Fundamentals

Core Concepts

The RBAC system consists of several key elements:

• Roles: Sets of permissions that can be assigned to users
• Subjects: Resources that can be acted upon (pages, files, events, etc.)
• Actions: Operations that can be performed on subjects (read, create, update, etc.)
• Rules: Define which roles can perform which actions on which subjects
• Conditions: Optional criteria that further restrict when rules apply

These components work together to create a flexible yet secure access control system.

Authorization Structure

RBAC configuration is defined in YAML format and consists of two main sections:

authorizations:
  # Define roles
  roles:
    editor: {}
    custom_role: {}
    
  # Define access rules
  rules:
    - role: editor
      action: read
      subject: pages

You can access and edit this configuration through your workspace settings.

Default Roles

Prisme.ai includes several built-in roles:

• Owner: Created automatically for workspace creator, has full access
• Editor: Can create and modify content but limited administrative access
• Custom Roles: Additional roles you define for specific needs

The Owner role is special and cannot be modified or deleted. It is automatically assigned to workspace creators and administrators.

Managing Roles and Rules

1. Accessing RBAC Settings

   To view and edit your workspace’s access control configuration:

   1. Go to your workspace
   2. Navigate to Settings > Advanced > Manage Roles
   3. Edit the YAML configuration
   4. Save your changes

   Changes to RBAC settings take effect immediately. Be careful not to lock yourself out!

2. Defining Roles

   Create custom roles to fit your organization’s needs:

   authorizations:
     roles:
       editor: {}  # Built-in role
       
       # Custom role for regular users
       user:
         auth:
           prismeai: {}  # Automatically assigned to all Prisme.ai users
           
       # Role for API access
       workspace:
         auth:
           apiKey: {}  # Can be used with API keys
   

   The auth section allows you to automatically assign roles based on authentication providers.

3. Creating Rules

   Define what each role can do with specific rules:

   rules:
     # Allow editors to read and update workspaces
     - role: editor
       action:
         - read
         - get_usage
         - aggregate_search
         - update
       subject: workspaces
       
     # Give editors full control over files
     - role: editor
       action: manage  # Shorthand for all permissions
       subject: files
   

   Each rule must include at least:

   • action: What can be done (a single action or list)
   • subject: What it can be done to (a single subject or list)

   Rules can optionally specify:

   • role: Which role this applies to (if omitted, applies to everyone)
   • conditions: Restrict the rule to specific cases. If omitted (or an empty object), the rule will apply to every instance of specified subject
   • inverted: Set to true to make this a deny rule instead of allow
   • reason: Documentation string for the rule
4. Adding Conditions

   Restrict rules to specific situations with conditions:

   # Allow access only to pages with a "public" label
   - action: read
     subject: pages
     conditions:
       labels:
         $in:
           - public
   
   # Deny editor access to API key events
   - role: editor
     inverted: true
     action: read
     subject: events
     conditions:
       type:
         $regex: ^apikeys\.*$
   

   Conditions use a subset of MongoDB query syntax for powerful filtering.

Common RBAC Patterns

Public Access

Control what unauthenticated users can access:

# Allow anyone to read pages with "public" label
- action: read
  subject: pages
  conditions:
    labels:
      $in:
        - public
        
# Allow anyone to create events (for automations)
- action: create
  subject: events
  conditions:
    source.serviceTopic: topic:runtime:emit
  reason: Anyone can create any events

Rules without a role specified apply to everyone, including unauthenticated users.

Role-Based Access

Define what each role can do:

# User role can read all pages
- role: user
  action:
    - read
  subject: pages

# Editor role can read and update pages
- role: editor
  action:
    - read
    - update
  subject: pages

This approach creates a clear hierarchy of access permissions.

API Key Permissions

Configure permissions for API access:

# Define workspace role for API access
roles:
  workspace:
    auth:
      apiKey: {}
      
# Grant specific permissions to this role
rules:
  - role: workspace
    action:
      - read
      - manage_permissions
    subject:
      - workspaces
      - events
      - pages
      - files

This allows creating an internal workspace API key with specific permissions.
The api key value can’t be directly accessed, but instead can be injected in fetch instruction :

  - fetch:
      url: '...'
      prismeaiApiKey:
        name: workspace

Automatic assignment

Automatically assign roles based on SSO provider & auth data :

roles:
  # Assign user role to all Prisme.ai & yourOwnSso authenticated users
  user:
    auth:
      prismeai: {}
      yourOwnSso: {}
      
  # Assign admin role to users from a specific email domain
  admin:
    auth:
      prismeai:
        conditions:
          authData.email:
            $regex: ^.*@mycompany.com$

This reduces manual user management by leveraging authentication information.

Subjects and Actions

RBAC controls access to various resource types through subject and action combinations:

Workspaces

Subject : workspaces

Actions :

• read : allows reading the workspace configuration
• update : allows updating the workspace configuration
• delete : allows deleting the workspace
• manage_security : allows updating security configuration
• manage_permissions : allows sharing / unsharing
• aggregate_search : allows using /search API
• get_usage : allows using /usage API
• manage_repositories : allows managing repositories settings
• manage : allows all above actions

Pages

Subject : pages

Actions :

• create : allows creating a page
• read : allows reading pages
• update : allows updating pages
• delete : allows deleting pages
• manage : allows all above actions

Files

Subject : files

Actions :

• create : allows uploading a file
• read : allows reading files
• update : allows updating files
• delete : allows deleting files
• manage : allows all above actions

Events

Subject : events

Actions :

• create : allows emitting an event
• read : allows reading events
• manage : allows all above actions

Automations

Subject : automations

Actions :

• create : allows creating an automation
• read : allows reading automations
• update : allows updating automations
• delete : allows deleting automations
• execute : allows executing automations
• manage : allows all above actions

Secrets

Subject : secrets

Actions :

• create : allows creating secrets
• read : allows reading secrets
• update : allows updating secrets
• delete : allows deleting secrets
• manage : allows all above actions

Secure secrets

Subject : secure_secrets

Actions :

• create / update : allows depositing a credential
• read : allows replaying one, which only an automation taking on a role can do

Secure secrets hold credentials, so this subject is narrower than the others: values are resolved by the runtime through {{secret.*}} and never handed back to a caller, whatever the rule says. What a rule must prove depends on who it applies to. See Secure secrets below.

Apps

Subject : apps

Actions :

• create : allows publishing an app
• read : allows viewing/installing apps
• update : allows updating apps
• delete : allows deleting apps
• manage : allows all above actions

Secure secrets

Secure secrets store credentials: an OAuth refresh token a member deposits when connecting their account, an API key a connector needs. Two rules describe their lifecycle, and they are deliberately asymmetric.

Letting members deposit their own credential

authorizations:
  rules:
    - action:
        - create
        - update
      subject: secure_secrets
      conditions:
        name:
          $regex: '^spnRefresh_[a-f0-9]{16}_${user.id}$'

The name condition is what isolates members from each other, so it is mandatory and checked when the workspace is saved. It must pin ${user.id}, anchored, with every other character a literal. Without it, one rule would let any member overwrite every other member’s credential.

A single fixed-width character class such as [a-f0-9]{16} is allowed, so a connector can hold one credential per remote account rather than one per person. Its width must be fixed: with a variable one, two different pairs could spell the same name.

manage is never grantable here, and delete only to a role (below). read is accepted, but a rule carrying no role applies to every member, so granting it here would let each of them read all the others’ credentials — the platform lets you write it and does not recommend it.

Letting an automation replay them

A scheduled synchronisation, or any automation acting for the workspace rather than for its caller, has no user behind it. It cannot read a credential under anyone’s permissions, which is exactly the problem: the tokens the workspace’s own members deposited are unreadable to its own sync.

Nothing about the shape of a run answers that. An unauthenticated cron and an unauthenticated HTTP call are indistinguishable, so the workspace states it instead: it declares a role, and the automation takes that role on for the one call that needs it.

authorizations:
  roles:
    tokenResolver: {}
  rules:
    - action:
        - create
        - update
      subject: secure_secrets
      conditions:
        name:
          $regex: '^spnRefresh_[a-f0-9]{16}_${user.id}$'

    - role: tokenResolver
      action:
        - read
        - create
        - update
        - delete
      subject: secure_secrets
      conditions:
        name:
          $regex: '^spnRefresh_'

delete belongs there for the same reason as the write: a connector that sees a token rejected for good drops it, so the run stops retrying and the member is asked to reconnect. It is grantable only to a role — on a rule that applies to every member it would hand each of them the right to destroy the others’ credentials.

- run:
    function: secret.get
    assumeRole: tokenResolver
    parameters:
      name: 'spnRefresh_{{targetUserId}}'
      scope: workspace

assumeRole applies to that single call. Everything around it keeps the caller’s own rights, and nothing is carried to the automations it calls, to an emit, or across a workspace boundary.

What each rule has to prove

The two rules above look alike and answer different questions.

A rule carried by no role lands on default, which applies to every member. Writing a name they choose would let one member overwrite another’s credential, so ${user.id} is mandatory there: it is the only thing keeping members apart.

A rule carried by a role applies to whoever takes it on, which is an automation acting for the workspace. It may name a family of secrets instead, for reads and writes alike. Reads, because a synchronisation serves everyone and there is no user to bind to. Writes, because providers that rotate their refresh tokens hand back a new one that has to be stored for a member who is not there.

A family pattern must carry a literal prefix of at least six characters ending on a separator, and can never reach the reserved prismeai_ namespace.

Anything holding that role can read and overwrite every credential in the family. That is the price of servicing absent users, and it is why the role should be declared for that purpose alone: do not grant it to a person, and do not give it an auth block. An API key bound to it would hand every member’s credential to whoever holds the key. The platform does not prevent either: it is yours to decide.

Two things remain out of reach whatever the role. Secrets of scope: user belong to a person, and a run without one is refused before permissions are even consulted. And owner cannot be assumed at all, so a developer has to declare a role that states what it opens rather than reaching for everything.

Securing Automations

By default, anyone can execute any automation that has an event or endpoint trigger. To restrict access to sensitive automations:

1. Define Authorization Action

   In your automation, specify an authorization requirement:

   slug: getAnalytics
   name: "Admin Page: Init Analytics"
   description: "Restricted automation for admin use only"
   when:
     events:
       - initAnalytics
   do:
     - emit:
         event: updateAnalytics
         payload:
           data: [...]
   authorizations:
     action: admin  # This is the authorization key
   

   The authorizations.action field specifies a permission key for this automation.

2. Create Permission Rule

   Define who can execute automations with this authorization key:

   # Allow admin role to execute automations with "admin" authorization
   - role: admin
     action: execute
     subject: automations
     conditions:
       authorizations.action:
         $in:
           - admin
   

   This restricts execution only to users with the specified role.

3. Test the Restriction

   Verify that:

   • Users with the admin role can execute the automation
   • Users without the admin role receive an authorization error
   • The automation cannot be called indirectly by other automations without permission

Using API Keys

External API Keys

API keys allow programmatic access to your workspace with specific permissions :

1. Use Prismeai APIs to generate an api key :

curl --location 'https://api.studio.prisme.ai/v2/workspaces/<WORKSPACE_ID>/security/apiKeys' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "api key name",
  "rules": [
      {
          "action": "create",
          "subject": "files"
      },
      {
          "action": ["create", "update", "read"],
          "subject": "pages",
          "conditions": {
              "labels": {
                  "$in": ["internal"]
              }
          }
      }        
  ]
}'  

2. Include the received apikey in x-prismeai-api-key header :

fetch('https://api.studio.prisme.ai/v2/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-prismeai-api-key': 'your-api-key'
  },
  body: JSON.stringify({ type: 'custom-event', payload: { data: 'value' } })
});

Keep API keys secure. They grant access based on their associated role without requiring user authentication.

Workspace API Keys

For internal API calls from automations, you can define built-in API keys:

roles:
  workspace:
    auth:
      apiKey: {}
      
rules:
  - role: workspace
    action:
      - read
      - aggregate_search
    subject:
      - workspaces
      - events

This creates an internal API key that automations can use:

- Prismeai API.searchEvents:
    query:
      type: user-login
    prismeaiApiKey:
      name: workspace
    output: events

Workspace API keys are not visible in the UI and are specifically for internal use.

Example RBAC Configuration

Here’s a complete example of a typical RBAC configuration:

Full RBAC Example

authorizations:
  roles:
    editor: {}
    user:
      auth:
        prismeai: {}
    workspace:
      auth:
        apiKey: {}
  rules:
    # Public access rules
    - action: read
      subject: pages
      conditions:
        labels:
          $in:
            - public
            
    # Workspace API key permissions
    - role: workspace
      action:
        - read
        - manage_permissions
      subject:
        - workspaces
        - events
        - pages
        - files
    - role: workspace
      action:
        - update
      subject:
        - files
        
    # User role permissions
    - role: user
      action:
        - read
      subject: pages
      
    # Editor role permissions
    - role: editor
      action:
        - read
        - get_usage
        - aggregate_search
        - update
      subject: workspaces
    - role: editor
      action: manage
      subject: files
    - role: editor
      action:
        - read
        - update
      subject: pages
    - role: editor
      action:
        - read
        - update
      subject: apps
    - role: editor
      action:
        - read
        - create
      subject: events
        
    # Editor role restrictions
    - role: editor
      inverted: true
      action: read
      subject: events
      conditions:
        type:
          $regex: ^apikeys\.*$
          
    # Public event access
    - action: create
      subject: events
      reason: Anyone can create any events
      conditions:
        source.serviceTopic: topic:runtime:emit
    - action: read
      subject: events
      conditions:
        source.serviceTopic: topic:runtime:emit
        source.sessionId: '{{session.id}}'
      reason: Anyone can read any events from its own session
      
    # Public file upload
    - action: create
      subject: files
      conditions:
        mimetype:
          $regex: ^(.*)$
      reason: Anyone can upload any file

Security Best Practices

Principle of Least Privilege

Give users only the permissions they actually need:

• Start with minimal permissions and add as required
• Use specific conditions to limit rule scope
• Avoid “manage” permission when more specific actions suffice
• Regularly review and prune unnecessary permissions

Secure Public Access

Carefully control what unauthenticated users can do:

• Use explicit conditions on public rules
• Limit event creation to specific event types
• Be cautious with file upload permissions
• Restrict user session events appropriately

Protect Sensitive Automations

Secure automations that access sensitive data:

• Add authorization requirements to important automations
• Create specific roles for administrative functions
• Avoid sensitive data exposure through events
• Test automations with different user roles

Manage API Access

Control programmatic access carefully:

• Create API keys with minimal required permissions
• Rotate API keys regularly
• Monitor API key usage for unusual patterns
• Delete unused API keys promptly

Troubleshooting

Access Denied Unexpectedly

When users encounter permission errors they shouldn’t:

Check these common issues:

• Verify the user has the correct role assignment
• Look for inverted rules (deny rules) that might be applying
• Check if conditions on rules are unintentionally restrictive
• Ensure the rule order places more specific rules after general ones

Example fix:

# Add a more permissive rule for this specific case
- role: user
  action: read
  subject: pages
  conditions:
    category: reports

Too Much Access

When users have permissions they shouldn’t have:

Check these common issues:

• Look for overly broad rules without conditions
• Check if the user has multiple roles granting cumulative permissions
• Verify automatic role assignment isn’t giving unintended access
• Ensure public rules (no role specified) aren’t too permissive

Example fix:

# Add a specific deny rule
- role: user
  inverted: true
  action: read
  subject: pages
  conditions:
    category: admin
    
# Or make existing rules more specific
- role: user
  action: read
  subject: pages
  conditions:
    category: 
      $ne: admin

Next Steps

Automations

Explore automations and their security model