Role-Based Access Control

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

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.

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.

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.

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

Accessing RBAC Settings

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

Go to your workspace
Navigate to Settings > Advanced > Manage Roles
Edit the YAML configuration
Save your changes

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

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.

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

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

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.

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.

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

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:

Securing Automations

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

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.

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.

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

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

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"]
              }
          }
      }        
  ]
}'  

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.

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:

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

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

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

Authentication

Learn about user identity and authentication

API Security

Secure programmatic access to your workspaces

Automations

Explore automations and their security model

Enterprise Integration

Connect with SSO and enterprise identity systems

Overview

AI SecureChat

AI Store

AI Knowledge

AI Builder

AI Governance

AI Collection (beta)

AI Insights (beta)

Role-Based Access Control

RBAC Fundamentals

Managing Roles and Rules

Common RBAC Patterns

Subjects and Actions

Securing Automations

Using API Keys

Example RBAC Configuration

Security Best Practices

Principle of Least Privilege

Secure Public Access

Protect Sensitive Automations

Manage API Access

Troubleshooting

Next Steps

Authentication

API Security

Automations

Enterprise Integration

Overview

AI SecureChat

AI Store

AI Knowledge

AI Builder

AI Governance

AI Collection (beta)

AI Insights (beta)

​RBAC Fundamentals

​Managing Roles and Rules

​Common RBAC Patterns

​Subjects and Actions

​Securing Automations

​Using API Keys

​Example RBAC Configuration

​Security Best Practices

Principle of Least Privilege

Secure Public Access

Protect Sensitive Automations

Manage API Access

​Troubleshooting

​Next Steps

Authentication

API Security

Automations

Enterprise Integration

RBAC Fundamentals

Managing Roles and Rules

Common RBAC Patterns

Subjects and Actions

Securing Automations

Using API Keys

Example RBAC Configuration

Security Best Practices

Troubleshooting

Next Steps