Kodexa uses a Fine-Grained Access Control (FGAC) system built on teams, roles, and permissions. This model controls what users can see and do across the platform at both the organization and project levels.
Overview
The security model has four key concepts:
- Users are people who log in to the platform
- Teams group users together
- Roles define a set of permissions
- Assignments grant a team a role at the organization or project level
Users never receive permissions directly. Instead, permissions flow through the team-role-assignment chain:
User → Team → Assignment (org or project) → Role → Permissions
A user’s platform role (set when the user is first provisioned) is a separate concept from the FGAC roles, teams, and permissions described below. Platform roles decide which top-level surfaces a user can reach (Studio, Workflow, Knowledge); FGAC decides what that user can do with individual resources inside an organization or project.
| Role | Description |
|---|
PLATFORM_ADMIN | Full platform administrator. Bypasses FGAC permission checks. |
SUPPORT | Support access. |
STUDIO | Access to the Studio surface. |
WORKFLOW | Access to the Workflow surface. |
WORKFLOW_KIOSK | Restricted, task-mode kiosk access. Reaches the Workflow surface only, locked into the kiosk task-review UI. |
KNOWLEDGE | Access to the Knowledge surface. |
WORKFLOW_KIOSK reaches the Workflow surface and is locked into the kiosk (task-review) UI. A user who holds both WORKFLOW and WORKFLOW_KIOSK can toggle kiosk mode on and off from their organization home.
Default Role on Provisioning
When a new user signs in for the first time, the platform provisions their user record from the Auth0 identity token and assigns platform roles using the following precedence:
@kodexa.com email → PLATFORM_ADMIN. Users with a kodexa.com email address are automatically made platform admins. This takes precedence even when the token carries no roles.- No token roles →
WORKFLOW_KIOSK. If the Auth0 token carries no roles for a non-kodexa.com user, the user defaults to the restricted WORKFLOW_KIOSK platform role (task-mode kiosk). This is the entry point for new users until an administrator grants broader roles.
- Token roles are not adopted as platform roles. Roles carried in the identity token are recorded on the user record’s raw
roles_json field but are NOT copied into the platform-role set that gates surfaces. The WORKFLOW_KIOSK default is applied only when the token carries no roles; when the token does carry roles for a non-kodexa.com user, the platform neither forces the kiosk default nor grants any platform role from the token — the user starts with no platform roles until an administrator assigns them.
The default only applies at first provisioning. Once a user exists, an administrator changes their platform roles directly on the user record — for example, to grant WORKFLOW, STUDIO, or KNOWLEDGE access beyond the initial kiosk role.
resource:action pair. For example:
| Permission | Meaning |
|---|
document-family:read | Can read document families |
task:lock | Can lock tasks |
document-store:upload | Can upload to document stores |
*:read | Can read any resource type |
*:* | Full access to everything |
* wildcard matches any resource type or action. This allows roles to grant broad access (like *:read for read-only) or full access (*:* for admins).
Standard Actions
These actions map to standard CRUD operations:
| Action | HTTP Method | Description |
|---|
create | POST | Create new resources |
read | GET | View resources |
update | PUT/PATCH | Modify resources |
delete | DELETE | Remove resources |
Custom Actions
Beyond CRUD, the platform defines custom actions for domain-specific operations:
| Action | Description |
|---|
lock | Lock a document family or task |
unlock | Unlock a document family or task |
reprocess | Reprocess a document family |
rename | Rename a document family |
label | Add or remove labels |
assign | Manage assignees on tasks or documents |
assign-next | Auto-assign next available task |
update-status | Change status of a task or document |
upload | Upload files to stores or modules |
export | Export document data |
assess | Assess a document family |
manage-features | Add or remove knowledge features |
activate | Activate an assistant |
deactivate | Deactivate an assistant |
trigger | Trigger an assistant event or schedule |
invoke | Invoke an agent |
cancel | Cancel an execution |
Teams
Teams are the bridge between users and access control. A team belongs to an organization and can have any number of members.
Key points about teams:
- A user can belong to multiple teams
- Each team has a unique slug within its organization (e.g.,
extraction-team)
- Teams are managed from the Members & Teams page in organization settings
- Task templates can reference teams by slug for automatic task routing
Roles
Roles define what a team can do. The platform ships with system-defined roles that cover common access patterns. If you need a custom role tailored to your organization, contact Kodexa Support.
System-Defined Roles
Organization Roles
| Role | Permissions | Use Case |
|---|
| org-owner | *:* (full access) | The organization creator. Cannot be removed. |
| org-admin | *:* (full access) | Administrators who manage teams, roles, and all resources. |
| org-member | All CRUD + all custom actions | Regular members who work with resources but don’t manage teams or org settings. |
| org-viewer | *:read, *:export | Stakeholders or auditors with read-only access across the org. |
Project Roles
| Role | Permissions | Use Case |
|---|
| project-admin | *:* (full access) | Project leads who manage all project resources. |
| project-editor | Create, read, update + all 17 custom actions (no delete) | Team members who actively work with documents, tasks, and knowledge. |
| project-contributor | Create, read, update, upload, update-status | Users who submit data and update statuses but don’t manage assignments or reprocess. |
| project-viewer | Read + export | Users who review results without modifying anything. |
Access Assignment
Teams receive roles through assignments at two levels:
Organization-Level Assignment
When a team is assigned a role at the organization level, all team members receive those permissions across every resource in the organization.
Project-Level Assignment
When a team is assigned a role at the project level, members receive those permissions only for resources linked to that project.
How Permission Checks Work
When a user makes an API request, the platform evaluates permissions in this order:
The check flow in detail:
- Authentication — Is the user logged in? If not, return 401.
- Platform Admin bypass — Platform admins (
platform_admin role) skip all permission checks.
- Organization-level check — Look up the user’s teams, find team-org assignments for this org, collect all permissions from assigned roles. If the required permission matches, allow.
- Project-level check — Find which projects this resource is linked to (via
project_resources). For each project, look up the user’s team-project assignments and check permissions. If any project grants the required permission, allow.
- Deny — If no check grants the permission, return 403.
Effective Permissions
A user’s effective permissions in a given context are the union of:
- Permissions from all org-level team assignments in that organization
- Permissions from all project-level team assignments for the relevant project
You can query a user’s effective permissions:
GET /api/account/permissions?organizationId={orgId}&projectId={projectId}
{
"permissions": ["*:create", "*:read", "*:update", "*:lock", "*:unlock", "..."],
"organizationId": "org-123",
"projectId": "proj-456"
}
Complete Example
Here’s a full example showing how Alice gets access to work on documents in the Invoice Project:
Setup steps:
- An admin creates the Extraction Team in Acme Corp
- Alice is added as a team member
- The team is given a project-level assignment in Invoice Project with the project-editor role
- Alice can now create, read, update, lock, unlock, reprocess documents — but cannot delete anything in Invoice Project
If Alice also needs read-only access to the Contract Project, the admin creates a second assignment for the Extraction Team in that project with the project-viewer role.
API Endpoints
| Endpoint | Purpose |
|---|
GET/POST /api/teams | Manage teams |
GET/POST /api/team-members | Manage team membership |
GET/POST /api/team-org-assignments | Assign teams to orgs with roles |
GET/POST /api/team-project-assignments | Assign teams to projects with roles |
GET /api/roles | List available roles |
GET /api/permissions | List available permissions |
GET /api/role-permissions | List role-permission links |
GET /api/account/permissions | Get current user’s effective permissions |
