Skip to main content
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:
  1. Users are people who log in to the platform
  2. Teams group users together
  3. Roles define a set of permissions
  4. 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

​
Permission Format

Every permission is a resource:action pair. For example:
PermissionMeaning
document-family:readCan read document families
task:lockCan lock tasks
document-store:uploadCan upload to document stores
*:readCan read any resource type
*:*Full access to everything
The * 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:
ActionHTTP MethodDescription
createPOSTCreate new resources
readGETView resources
updatePUT/PATCHModify resources
deleteDELETERemove resources

​
Custom Actions

Beyond CRUD, the platform defines custom actions for domain-specific operations:
ActionDescription
lockLock a document family or task
unlockUnlock a document family or task
reprocessReprocess a document family
renameRename a document family
labelAdd or remove labels
assignManage assignees on tasks or documents
assign-nextAuto-assign next available task
update-statusChange status of a task or document
uploadUpload files to stores or modules
exportExport document data
assessAssess a document family
manage-featuresAdd or remove knowledge features
activateActivate an assistant
deactivateDeactivate an assistant
triggerTrigger an assistant event or schedule
invokeInvoke an agent
cancelCancel 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

RolePermissionsUse Case
org-owner*:* (full access)The organization creator. Cannot be removed.
org-admin*:* (full access)Administrators who manage teams, roles, and all resources.
org-memberAll CRUD + all custom actionsRegular members who work with resources but don’t manage teams or org settings.
org-viewer*:read, *:exportStakeholders or auditors with read-only access across the org.

​
Project Roles

RolePermissionsUse Case
project-admin*:* (full access)Project leads who manage all project resources.
project-editorCreate, read, update + all 17 custom actions (no delete)Team members who actively work with documents, tasks, and knowledge.
project-contributorCreate, read, update, upload, update-statusUsers who submit data and update statuses but don’t manage assignments or reprocess.
project-viewerRead + exportUsers 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:
  1. Authentication — Is the user logged in? If not, return 401.
  2. Platform Admin bypass — Platform admins (platform_admin role) skip all permission checks.
  3. 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.
  4. 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.
  5. 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}
Response: 
{
  "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:
  1. An admin creates the Extraction Team in Acme Corp
  2. Alice is added as a team member
  3. The team is given a project-level assignment in Invoice Project with the project-editor role
  4. 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

EndpointPurpose
GET/POST /api/teamsManage teams
GET/POST /api/team-membersManage team membership
GET/POST /api/team-org-assignmentsAssign teams to orgs with roles
GET/POST /api/team-project-assignmentsAssign teams to projects with roles
GET /api/rolesList available roles
GET /api/permissionsList available permissions
GET /api/role-permissionsList role-permission links
GET /api/account/permissionsGet current user’s effective permissions