> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions Management

> Learn how super-admins, organization roles, and workspace roles combine to control access across the Prisme.ai platform

Prisme.ai's authorization model has three independent layers. Each one is configured in a different place and answers a different question.

<CardGroup cols={3}>
  <Card title="Super Admins" icon="user-crown">
    Platform-wide access — every workspace, every organization. Configured at the infrastructure level.
  </Card>

  <Card title="Organization Roles" icon="building-shield">
    A user belongs to **one organization at a time**. Their role in that org grants permissions on the products (Agent Creator, Knowledges, Insights, Governe, …) scoped to that org's resources.
  </Card>

  <Card title="Workspace Roles" icon="folder-tree">
    Developer / editor / owner access on Builder workspaces. Shared workspace-by-workspace, independent of organizations.
  </Card>
</CardGroup>

<Note>
  A user can be a member of several organizations but only operates in **one organization at a time**. Switching organizations changes which products and resources they see, and re-applies the role assigned in that org.
</Note>

## Key Concepts and Terminology

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

    * Accessible via the **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 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.** Knowledges, Agent Creator, AI Insights, for example, are products.

    * Listed below **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 the 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>

  <Tab title="Organizations">
    **Organizations are the tenant boundary around members, roles, and product resources.**

    * Every product resource (agents, knowledge bases, API keys, service accounts, …) belongs to an organization
    * Members join an organization with a role; that role defines what they can do inside the org
    * A user can be a member of several organizations but is **active in only one at a time**
    * SSO, join rules, invitation codes and groups are all managed at the organization level

    Organizations replace the legacy *Platform Manager* / *Group Manager* notion: there is no longer a global "platform" role — every administrative capability is granted through a role inside an organization.
  </Tab>
</Tabs>

## Organization Roles

Each organization defines its own set of roles. A role is a list of permissions following the `product:resource:action` pattern, optionally restricted to specific resource IDs via scopes. When a user is active in an organization, their role determines:

* Which products they can open (Agent Creator, Knowledges, Insights, Governe, Builder, …)
* What they can do inside each product (read / write / publish / share / delete)
* Which specific resources they can touch (one agent, all knowledge bases, a single LLM model, …)
* Whether they can manage the organization itself: members, groups, SSO, API keys, branding, navigation, join rules, …

<Note>
  **The full catalogue of permissions and the built-in roles** (`Owner`, `Admin`, `Member`, `Agent Maker`, `Builder`, `Agent Standard`) is documented in **[Governe → Identity & Access → Roles & Permissions](/products/ai-governance/identity-access#roles--permissions)**. That page is the source of truth — this page only covers how organization roles fit into the broader authorization model.
</Note>

### Per-resource RBAC

In addition to the scopes declared on a role, Agent Factory and Knowledge projects expose their own **Share** dialog: a resource (one agent, one knowledge base) can be shared with specific users or groups under a product-managed role that maps back to the same `product:resource:action` permissions.

<Warning>
  **Org role and resource role are intersected, not unioned.** An action on a resource succeeds only when the equivalent permission is granted **both** by the user's active organization role **and** by their role on the resource. Granting Editor on a single agent does not bypass the org role — if the org role does not include `agent-factory:agents:write`, the user still cannot edit the agent.
</Warning>

### Managing members and roles

Members and their roles are managed inside each organization through the **Governe** module. Any role that carries the `orgs:members:manage` permission can invite users, change their role, suspend or remove them — that capability replaces the legacy *Platform Manager* / *Group Manager* roles, which no longer exist.

For the four onboarding mechanisms (email invite, invitation code, join rules, SSO auto-join), see [Governe → Joining an Organization](/products/ai-governance/identity-access#joining-an-organization).

### Custom roles

Organizations can extend the built-in roles or define entirely new ones via the **Permission Tree Editor** in Governe. Each system role except `Owner` can also be overridden per organization. See [Governe → Creating Custom Roles](/products/ai-governance/identity-access#creating-custom-roles).

## Workspace Roles

Workspace roles control who can access and modify specific Builder workspaces. They are **independent of organization roles** — a workspace is shared user-by-user (or via SSO security rules), and the role granted there applies inside that workspace regardless of which organization the user is currently active in.

<Accordion title="Available Roles">
  Workspaces support several 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 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>

<Accordion title="SSO security rules on a workspace">
  Workspaces can declare custom security rules so that end users authenticated via SSO automatically receive a role inside the workspace — typically read-only access to a few pages:

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

  With this configuration, every user authenticated via `yourOwnSso` receives the `user` role and can read every page labelled `users`. See [RBAC for more advanced rules](/products/ai-builder/rbac).
</Accordion>

## Super Admins

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

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

  * Access, share, and update **every existing workspace**
  * Access **every organization** as if they were a member with full rights
  * View all events, configurations, and automations
  * Install, update, and configure Prisme.ai products
  * Manage all aspects of the platform

  This is the most powerful role — essentially owner of every workspace and every organization.
</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 `prismeai-api-gateway.config.admins` helm value in the `prismeai-core` chart:

  ```yaml theme={null}
  prismeai-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, give yourself a regular org role with the right permissions instead of relying on Super Admin status
  * Regularly review and audit the list of Super Admin accounts
</Accordion>

## 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 org roles that align with job functions
    * Assign users to those roles instead of granting one-off permissions
    * Use scopes to restrict roles to specific agents, knowledge bases, models, …
  </Card>

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

    * Schedule regular permission reviews per organization
    * 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 an action, permissions are evaluated across the three layers:

<Steps>
  <Step title="Authentication">
    The system verifies the user is properly authenticated — local credentials, SSO provider, or an API key / service account token.
  </Step>

  <Step title="Super Admin check">
    If the user is a Super Admin, they bypass org-level and workspace-level restrictions and have full access everywhere.
  </Step>

  <Step title="Active organization role">
    For product access (Agent Creator, Knowledges, Insights, Governe, …), the platform looks up the role assigned to the user **in their currently active organization** and evaluates its permissions and scopes against the requested resource. Resources owned by other organizations are invisible.
  </Step>

  <Step title="Per-resource role (Agent Factory / Knowledge)">
    When the resource was shared individually via a project's **Share** dialog, the platform also evaluates the role assigned on that specific resource. The org role and the resource role are **intersected** — both must grant the equivalent permission for the action to succeed.
  </Step>

  <Step title="Workspace role">
    For Builder workspace access, the platform checks the workspace's own sharing list (explicit grants + SSO security rules). This is independent of the organization role.
  </Step>
</Steps>

<Warning>
  Organization access and workspace access are separate layers. A user can be Admin of an organization (full access to its products) without having any access to the workspaces that power those products — and vice versa.
</Warning>

## Common Permission Scenarios

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

  **Recommended setup**:

  * Super Admin status (via `SUPER_ADMIN_EMAILS` or helm)
  * `Owner` role in the main operating organization
  * Workspace owner on the critical workspaces (Knowledges, Agent Creator, …)

  This combination provides full system access for installation, maintenance, and emergency intervention.
</Accordion>

<Accordion title="Organization Admin">
  **Description**: Business owner of an organization — manages members, branding, SSO, and product access

  **Recommended setup**:

  * `Admin` role in the organization (`orgs:members:manage`, `orgs:sso:manage`, `orgs:branding:manage`, …)
  * No Super Admin
  * No workspace access unless they also build automations

  This role replaces the legacy *Platform Manager* / *Group Manager*: the right to manage users is now just one permission inside an organization role.
</Accordion>

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

  **Recommended setup**:

  * `Builder` role in the organization (gives `builder:*` plus the agent-factory and storage permissions)
  * Editor or Owner role on the specific workspaces they own
  * No Super Admin access

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

<Accordion title="Agent Maker / Business User">
  **Description**: Domain expert creating agents and knowledge bases without touching workspaces

  **Recommended setup**:

  * `Agent Maker` role in the organization
  * No workspace access
  * No Super Admin

  The user can create agents and knowledge bases inside their organization, scoped to the resources their role allows.
</Accordion>

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

  **Recommended setup**:

  * `Member` role in the organization (read-only on most resources, full access to chat)
  * Optional workspace SSO security rules grant page-level access to specific user interfaces
  * No Super Admin

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

## Troubleshooting Permission Issues

<Accordion title="User cannot access a product (Agent Creator, Knowledges, Insights, …)">
  **Possible causes**:

  * The user is active in the wrong organization
  * Their role in the active organization does not include the required permission
  * The resource belongs to another organization

  **Resolution steps**:

  1. Confirm which organization the user is currently active in
  2. In **Governe → Members**, check the role assigned to that user
  3. In **Governe → Roles**, verify the role's permissions and scopes
  4. If needed, assign a richer role or create a custom one
</Accordion>

<Accordion title="User cannot access a workspace">
  **Possible causes**:

  * The user has not been explicitly added to the workspace's sharing list
  * The workspace's SSO security rules do not match the user
  * The user's email address is misspelled

  **Resolution steps**:

  1. Open the workspace in Builder and check the **Share** dialog
  2. Verify the user's email address matches exactly
  3. Review the workspace's `authorizations.rules` if SSO-driven access is expected
  4. Explicitly grant a workspace role if needed
</Accordion>

<Accordion title="Super Admin cannot perform an action in a product">
  **Possible causes**:

  * The product applies its own permission check inside automations that don't recognize the super-admin flag
  * The Super Admin is currently active in an organization where the resource doesn't exist

  **Resolution steps**:

  1. Switch to the organization that owns the resource
  2. Check the automation logs to see which permission check failed
  3. Grant the Super Admin a role with the required permission inside that organization, or update the automation's permission logic
</Accordion>