> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-legacy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions Management

> Learn how to manage user access and permissions across different layers of the Prisme.ai platform

Prisme.ai implements a comprehensive, multi-layered authorization system that ensures secure access control across the platform. This guide explains how permissions work at each level and provides instructions for effective permission management.

## Understanding the Authorization Model

Prisme.ai's authorization system operates at four distinct layers:

<CardGroup cols={2}>
  <Card title="Super Admins" icon="user-crown">
    Technical or management users with platform-wide access configured at the infrastructure level
  </Card>

  <Card title="Workspace Roles" icon="folder-tree">
    Developer and manager permissions assigned on AI Builder workspace-by-workspace basis
  </Card>

  <Card title="SSO Access" icon="id-badge">
    End-user access controls configured for each workspace with SSO integration
  </Card>

  <Card title="Product Roles" icon="user-gear">
    Fine-grained permissions assigned to user groups within individual products
  </Card>
</CardGroup>

## Key Concepts and Terminology

Before diving into permission details, it's important to understand the distinction between two fundamental concepts:

<Tabs>
  <Tab title="Workspaces">
    **Workspaces are dedicated environments where you can build, manage, and run agents, as well as implement all custom or project-specific logic.**

    * Accessible via the **AI Builder** section in the left-hand menu
    * Similar to software management projects or team workspaces in traditional environments
    * Designed for tech teams to create, configure, and maintain AI-powered applications
    * Contain automations, blocks, pages, and other reusable development resources
    * Centralize all activity: end-user interactions, audit logs, and execution traces

    Workspaces are the foundation of Prisme.ai's AI Builder. They empower teams to design, test, and deploy custom AI solutions tailored to their unique business needs.
  </Tab>

  <Tab title="Products">
    **Products are user-facing applications built on workspaces.** AI Knowledge, AI Store, AI Insight, for example, are Products.

    * Listed below **AI Builder** in the left menu
    * Web pages, applications, or APIs designed for end users
    * End users interact with products but typically don't have access to underlying workspaces
    * Represent the "production" deployments of applications

    Products are what your end users will interact with, while the workspaces are where you build and configure these products.
  </Tab>
</Tabs>

Understanding this distinction is crucial because permissions are applied differently at the workspace level versus the product level.

## Product Roles

Product roles provide fine-grained control over what users can do within specific Prisme.ai products.

<Accordion title="Understanding Product Roles">
  Unlike workspace roles, which control access to development environments, product roles determine:

  * What features users can access within a product
  * What actions they can perform
  * What data they can view or modify

  These roles are managed through AI Governance and apply to the end-user experience of the products.
</Accordion>

<Accordion title="Example Product Roles">
  Different products come with predefined roles. For example, in AI Knowledge:

  * **Product Admin**: Can access analytics, all existing projects, and create new ones
  * **Knowledge User**: Can only access shared projects and cannot create new ones

  Product role capabilities are specific to each product and provide targeted permission controls.

  **Important Note**: Even users with the **Product Admin** role cannot change the product's configuration (e.g., LLM providers, models, rate limits) unless they also have access to the corresponding workspace.
</Accordion>

<Accordion title="Managing Product Roles through AI Governance">
  Role management is managed through the AI Governance module of the Prisme.ai platform.

  Access to this Governance module is granted to users with the Manager role "Platform Manager" or "Group Manager":

  * The "Platform Manager" Manager role allows the user to administer all configurable features of AI Governance.
  * The "Group Manager" Manager role allows the user to configure access for members of their group. They do not have access to role management, product management, or platform customization.
</Accordion>

Access to the different modules of the platform is configurable through the "Platform Role" Prisme.ai. These roles consist of distinct rights on the various modules:

<Accordion title="Builder">
  * **Authorized:** grants access to the AI Builder module of the Prisme.ai platform
</Accordion>

<Accordion title="AI Knowledge">
  * **Authorized:** grants access to the AI Knowledge module of the Prisme.ai platform and the bank of AI Knowledge projects shared with the user:
    * If the project was shared in "User" mode: the user can access the instantiated AI Store assistant of the AI Knowledge project
    * If the project was shared in "Editor" mode: the user can access the AI Knowledge project and all its settings. However, they cannot grant access to other users
    * If the project was shared in "Owner" mode: the user can access the AI Knowledge project and all its settings, including adding users

  * **Create Agents:** allows the user to create AI Knowledge projects and access all their settings

  * **Admin:** grants access to all AI Knowledge projects of the instance

  * **Publish agent:** grants the user the right to make the agent public via the "Settings" tab of an AI Knowledge project
</Accordion>

<Accordion title="AI Store">
  * **Authorized:** grants access to the AI Store module of the Prisme.ai platform and the bank of AI Store projects shared with the user

  * **Create Agents:** allows the user to create AI Store agents and access all their settings. To create AI Store Agents, the user must have the right to create AI Knowledge projects
</Accordion>

<Accordion title="AI Collection">
  * **Authorized:** grants access to the AI Collection module of the Prisme.ai platform and the bank of AI Collection projects shared with the user. The user also has the ability to create AI Collection projects
</Accordion>

<Accordion title="AI Insights">
  * **Authorized:** grants access to the AI Insights module of the Prisme.ai platform and the bank of supervision agents of Insights assistants that the user has created. The user also has the ability to create new AI Insights agents on AI Knowledge projects they have access to
</Accordion>

## Super Admins

Super Admins have the highest level of access across the entire Prisme.ai platform.

<Accordion title="Capabilities and Scope">
  Super Admins can:

  * Access, share, and update **every existing workspace**
  * View all events, configurations, and automations
  * Manage all aspects of the platform
  * Install, update, and configure Prisme.ai products

  This is the most powerful role and essentially makes the user an owner of every workspace.
</Accordion>

<Accordion title="Configuration">
  Super Admin access is configured at the infrastructure level:

  **Option 1: Environment Variable**

  Set the `SUPER_ADMIN_EMAILS` environment variable in the **api-gateway** microservice:

  ```bash theme={null}
  SUPER_ADMIN_EMAILS=admin1@example.com,admin2@example.com
  ```

  **Option 2: Helm Configuration**

  Configure via the `api-gateway.config.admins` helm value in the `prismeai-core` chart:

  ```yaml theme={null}
  api-gateway:
    config:
      admins:
        - admin1@example.com
        - admin2@example.com
  ```
</Accordion>

<Accordion title="Best Practices">
  While Super Admins have extensive privileges, we recommend:

  * Limiting the number of Super Admin accounts to minimize security risks
  * Using Super Admin accounts primarily for installation, updates, and platform configuration
  * For day-to-day operations, Super Admins should share important workspaces (AI Knowledge, AI Store...) with secondary accounts that have more limited permissions
  * Regularly review and audit the list of Super Admin accounts

  **Important Note:** Although Super Admins manage all workspaces, they might not automatically have admin access to all products since products can have their own permission layer. However, Super Admins can always grant themselves the necessary product permissions from the workspace level.
</Accordion>

## Workspace Roles

Workspace roles control who can access and modify specific workspaces in Prisme.ai.

<Accordion title="Available Roles">
  Workspaces support various roles with different permission levels:

  * **Owner**: Full control over the workspace, including sharing with others
  * **Editor**: Can modify workspace content but has limited administrative capabilities
  * **Custom Roles**: Additional roles can be defined with specialized permissions

  Each role determines what actions a user can perform within the workspace.
</Accordion>

<Accordion title="What Workspace Roles Control">
  Users with workspace access can:

  * Update workspace configuration and secrets
  * Search through activity events for debugging or auditing
  * Modify automations and pages to develop new features
  * Access the workspace's development environment
  * Deploy changes to associated products

  These permissions are critical for developers and administrators who need to build and maintain applications.
</Accordion>

<Accordion title="Managing Workspace Roles">
  To share a workspace with other users:

  1. Navigate to the workspace in the AI Builder section
  2. Click on the "Share" button in the workspace header
  3. Enter the email address of the user
  4. Select the appropriate role from the dropdown
  5. Click "Add" to grant access

  You can also modify or revoke existing permissions from this same interface.
</Accordion>

## SSO Access

SSO (Single Sign-On) access controls which end users can access product pages when authenticating through your identity provider.

<Accordion title="How SSO Access Works">
  Prisme.ai products like AI Knowledge and AI Store use custom security rules to automatically grant access to authenticated SSO users.

  These rules:

  * Are configured at the workspace level
  * Typically grant access only to the user-facing pages
  * Can be customized to provide different levels of access based on user attributes
  * Allow end users to access products without requiring individual account setup
</Accordion>

<Accordion title="Configuring SSO Access">
  To configure SSO access for a product:

  1. Access the product's workspace through AI Builder
  2. Navigate to the workspace settings
  3. Look for the Security or SSO section
  4. Configure the authentication providers
  5. Define rules for automatic role assignment based on user attributes

  For example, you might create rules that assign specific roles based on group membership in your identity provider :

  ```yaml theme={null}
  authorizations:
    roles:
      user:
        auth:
          yourOwnSso: {}
    rules:
      - role: user
        action:
          - read
        subject: pages
        conditions:
          labels: users
  ```

  With this security rules, every user authenticated with `yourOwnSso` will automatically have `user` role, defining the `{{user.role}} == "user"` variable and giving access to every pages with a `users` label.\
  See [RBAC for more advanced rules](/products/ai-builder/rbac)
</Accordion>

<Note>
  While SSO rules typically only grant access to user-facing pages, they can be configured to provide full workspace access, similar to [owner roles](#workspace-roles), if needed.
</Note>

## Permission Management Best Practices

<CardGroup cols={2}>
  <Card title="Least Privilege Principle" icon="shield-check">
    **Assign only the minimum permissions needed**

    * Grant users only the access they need to perform their jobs
    * Regularly review and revoke unnecessary permissions
    * Use time-limited access when possible for temporary needs
  </Card>

  <Card title="Role-Based Access Control" icon="users-gear">
    **Organize permissions by role, not individual users**

    * Create roles that align with job functions
    * Assign users to appropriate roles
    * Modify role definitions rather than creating one-off permissions
  </Card>

  <Card title="Regular Audits" icon="clipboard-check">
    **Review permissions periodically**

    * Schedule regular permission reviews
    * Check for outdated access after role changes
    * Audit Super Admin accounts especially carefully
  </Card>

  <Card title="Document Access Policies" icon="file-lines">
    **Create clear permission guidelines**

    * Document which roles have access to what resources
    * Establish approval processes for elevated access
    * Provide clear procedures for requesting access changes
  </Card>
</CardGroup>

## Understanding Permission Interactions

When a user attempts to perform an action in Prisme.ai, their permissions are evaluated across multiple layers:

<Steps>
  <Step title="Authentication Validation">
    First, the system verifies the user is properly authenticated, either through:

    * Local username/password
    * SSO provider credentials
    * API key or token validation
  </Step>

  <Step title="Super Admin Check">
    If the user is a Super Admin, they generally have full access to all workspaces but might still need specific product roles.
  </Step>

  <Step title="Workspace Permission Evaluation">
    For workspace access:

    * The system checks if the user has been explicitly granted a role
    * It evaluates any SSO-based role assignments
    * It determines the specific capabilities based on the assigned role
  </Step>

  <Step title="Product Permission Evaluation">
    For product features:

    * The system verifies product-specific roles assigned in AI Governance
    * It checks any group memberships that might grant additional permissions
    * It enforces feature and data access based on these roles
  </Step>
</Steps>

<Warning>
  Remember that workspace access and product access are separate layers. A user might have admin rights to a product without having access to its underlying workspace, or vice versa.
</Warning>

## Common Permission Scenarios

<Accordion title="Platform Administrator">
  **Description**: Technical staff responsible for platform management

  **Recommended Permissions**:

  * Super Admin status
  * Access to all critical workspaces (AI Knowledge, AI Store, etc.)
  * Product Admin roles in key products
  * Manager role in AI Governance

  This configuration provides full system access for platform maintenance and administration.
</Accordion>

<Accordion title="Developer">
  **Description**: Technical staff building applications and integrations

  **Recommended Permissions**:

  * Editor role in specific workspaces
  * Limited or no Super Admin access
  * Basic product access for testing
  * No AI Governance admin roles

  This setup allows developers to build and modify applications without unnecessary administrative access.
</Accordion>

<Accordion title="Department Manager">
  **Description**: Business stakeholder overseeing the use of specific products

  **Recommended Permissions**:

  * Product Admin role in relevant products
  * No workspace access (unless they need to make configuration changes)
  * No Super Admin access
  * Limited AI Governance access

  This configuration allows managers to administer their department's products without access to development environments.
</Accordion>

<Accordion title="End User">
  **Description**: Regular staff using AI products

  **Recommended Permissions**:

  * SSO access to product pages
  * Product-specific user roles
  * No workspace access
  * No AI Governance access

  This setup provides the appropriate access for day-to-day product usage without any administrative capabilities.
</Accordion>

## Troubleshooting Permission Issues

<Accordion title="User Cannot Access a Workspace">
  **Possible Causes**:

  * User has not been explicitly granted a workspace role
  * SSO configuration is not correctly mapping to workspace roles
  * User's email address might be misspelled in the permissions

  **Resolution Steps**:

  1. Check if the user appears in the workspace sharing settings
  2. Verify the user's email address matches exactly
  3. Check SSO configuration and attribute mapping
  4. Try explicitly granting a workspace role
</Accordion>

<Accordion title="User Cannot Access Product Features">
  **Possible Causes**:

  * User lacks the necessary product role
  * Product configuration is restricting access
  * User might not be in the required group

  **Resolution Steps**:

  1. Check the user's product roles in AI Governance
  2. Verify group memberships
  3. Check product-specific access settings
  4. Assign the appropriate product role
</Accordion>

<Accordion title="Super Admin Cannot Access a Product">
  **Possible Causes**:

  * Product has specific role requirements beyond Super Admin status
  * Product configuration issue

  **Resolution Steps**:

  1. Access the product's workspace
  2. Check the product configuration
  3. Modify settings or grant necessary product roles
  4. If needed, update the user's permissions in AI Governance
</Accordion>