Skip to content

docs(user-guide): document the invoker role #382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
s5unanow wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(user-guide): document the invoker role #382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 40 additions & 18 deletions docs/admin/security/roles-rbac.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@ The platform roles and their mapping to Keycloak realm roles and user attributes

## Roles in CodeMie

Five role levels are defined in CodeMie:
Six role levels are defined in CodeMie:

1. **Maintainer**
2. **Admin**
3. **Project Admin**
4. **Regular User**
5. **External User**
5. **Invoker**
6. **External User**

## How Keycloak Access Is Interpreted

Expand Down Expand Up @@ -52,28 +53,49 @@ Five role levels are defined in CodeMie:

## Role Descriptions

| Capability / Scope | Maintainer | Admin | Project Admin | Regular User | External User |
| -------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------ |
| Role level | Highest operational role | Platform-wide administrative role | Project-scoped administrative role | Standard user role | Special user type for guest/external scenarios |
| Platform-wide admin access | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage users and access assignments across the platform | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage key platform settings and operational views | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage budget and billing controls | ✅ (exclusive) | ❌ | ❌ | ❌ | ❌ |
| Manage members and project-level access | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ |
| View project-level analytics (including spending trends) | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ |
| View own usage and spending analytics | ✅ | ✅ | ✅ | ✅ | ✅ (where access is allowed) |
| Access scope | Platform-wide | Platform-wide | Assigned projects only | Assigned projects and knowledge sources | Regular-user scope with stricter limits where required |
| Assignment model | Assigned in CodeMie directly (not a separate Keycloak realm role) | Granted via Keycloak `admin` realm role | Derived from project attributes such as `applications_admin` | Derived from standard access assignments | Determined by external/guest user classification |
| Capability / Scope | Maintainer | Admin | Project Admin | Regular User | Invoker | External User |
| -------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Role level | Highest operational role | Platform-wide administrative role | Project-scoped administrative role | Standard user role | Run-only, least-privileged role | Special user type for guest/external scenarios |
| Platform-wide admin access | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage users and access assignments across the platform | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage key platform settings and operational views | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage budget and billing controls | ✅ (exclusive) | ❌ | ❌ | ❌ | ❌ | ❌ |
| Manage members and project-level access | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ | ❌ |
| View project-level analytics (including spending trends) | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ | ❌ |
| View own usage and spending analytics | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ (where access is allowed) |
| Create and configure assistants, workflows, and skills | ✅ | ✅ | ✅ | ✅ | ❌ (run shared ones and clone from Marketplace only) | ✅ (where access is allowed) |
| View assistant and workflow configuration | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ (where access is allowed) |
| Change the LLM model in a chat | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ (where access is allowed) |
| Manage personal integrations | ✅ | ✅ | ✅ | ✅ | ✅ (only credential types required by an accessible assistant) | ✅ (where access is allowed) |
| Access scope | Platform-wide | Platform-wide | Assigned projects only | Assigned projects and knowledge sources | Assigned projects only; every action is audited | Regular-user scope with stricter limits where required |
| Assignment model | Assigned in CodeMie directly (not a separate Keycloak realm role) | Granted via Keycloak `admin` realm role | Derived from project attributes such as `applications_admin` | Derived from standard access assignments | Assigned in CodeMie directly (`is_invoker` flag); exclusive with all administrative roles | Determined by external/guest user classification |

## Role Hierarchy

```
Maintainer ──► Admin ──► Project Admin ──► Regular User
│ │
│ └── Full platform access
└── Budget/billing management (exclusive)
Maintainer ──► Admin ──► Project Admin ──► Regular User ──► Invoker
│ │ │
│ └── Full platform access └── Run-only: no configuration
└── Budget/billing management (exclusive) visibility, no authoring
```

## Invoker Role

The **Invoker** sits below the Regular User. It is meant for people who should run assistants
and workflows that others have built, without seeing prompts, tools, models, data sources, or
any platform configuration. The interface is reduced to a chat-first experience.

- **Assignment**: set directly in CodeMie from Users Management (`is_invoker` flag on the user
account). It is not derived from Keycloak roles or attributes.
- **Exclusivity**: cannot be combined with Maintainer, Admin, Auditor, or Project Admin.
- **Prerequisite**: activity events (`ACTIVITY_EVENTS_ENABLED=True`) must be enabled; every
Invoker action and every denied request is written to the audit trail.
- **Enforcement**: the backend denies every API route outside the Invoker allow-list with
**Access denied**, so the restriction holds for direct API access as well as for the UI.

See [Invoker Role](../../user-guide/project-user-management/invoker-role.md) for the full list
of permitted and restricted actions.

:::info
For step-by-step instructions on assigning roles and attributes in Keycloak,
see the [Access Control](../configuration/access-control/index.md) section.
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/getting-started/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,10 @@ A configured connection between the CodeMie platform and an external service or

See [Default Integration](#default-integration) for how CodeMie selects one automatically when none is explicitly chosen.

### Invoker

The least-privileged platform role, identified by the `is_invoker` flag on the user account. An Invoker can chat with assistants and run workflows shared with their projects, clone Marketplace assistants into their personal project, and manage personal integrations, but cannot view or edit any assistant or workflow configuration, change the LLM model, author anything, or open administration screens. The role is assigned in Users Management, is mutually exclusive with Admin, Maintainer, Auditor, and Project Admin, and requires activity events to be enabled because every Invoker action is audited. See [Invoker Role](../project-user-management/invoker-role.md).

---

## J
Expand Down
29 changes: 20 additions & 9 deletions docs/user-guide/project-user-management/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,16 +46,27 @@ for setup instructions.
description="View all platform users, inspect individual user details, manage project assignments. Available to Platform Admins."
link="/user-guide/project-user-management/users"
/>
<FeatureCard
icon="/img/icons/protect.svg"
iconType="image"
invertInLightTheme={true}
title="Invoker Role"
description="A run-only, least-privileged role: chat with shared assistants, run workflows, clone from Marketplace, and manage personal integrations without access to any AI configuration."
link="/user-guide/project-user-management/invoker-role"
/>
</FeatureGrid>

## Access by Role

| Feature | Regular User (Project Admin) | Platform Admin |
| ----------------------------- | ---------------------------- | -------------- |
| Create a project | ✅ | ✅ |
| View own projects | ✅ | ✅ |
| Edit own project | ✅ | ✅ |
| Delete own empty project | ✅ | ✅ |
| Manage members in own project | ✅ | ✅ |
| View and manage all projects | ❌ | ✅ |
| Access Users Management | ❌ | ✅ |
| Feature | Invoker | Regular User (Project Admin) | Platform Admin |
| ----------------------------- | ------- | ---------------------------- | -------------- |
| Create a project | ❌ | ✅ | ✅ |
| View own projects | ✅ | ✅ | ✅ |
| Edit own project | ❌ | ✅ | ✅ |
| Delete own empty project | ❌ | ✅ | ✅ |
| Manage members in own project | ❌ | ✅ | ✅ |
| View and manage all projects | ❌ | ❌ | ✅ |
| Access Users Management | ❌ | ❌ | ✅ |

An **Invoker** is a run-only user who can use what is shared with them but cannot manage
projects, members, or any AI configuration. See [Invoker Role](./invoker-role.md).
Loading