Documentation Index
Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
Every permission is a 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 |
