Skip to main content

​
Overview

ORCA uses a layered permission system to control access across your organisation. Every user belongs to an organisation and can be assigned to one or more teams, each with its own permission set. Admins have full access by default; non-admin users inherit permissions from their custom role, team memberships, and individual overrides.

​
Role hierarchy

ORCA has two built-in system roles and supports custom roles for fine-grained control.
RoleAccess levelModifiable
AdminFull access to all features, settings, billing, and team managementNo
WorkerDefault permission set (see table below)No
Custom rolesAdmin-defined permission sets assigned to individual usersYes
System roles cannot be edited or deleted. Custom roles are org-scoped and can be created, updated, and deleted by admins.

​
Permission resolution order

When ORCA evaluates whether a user can perform an action, it checks in this order:
  1. Admin role — always granted
  2. Explicit user permission — per-user override (if set)
  3. Custom role — permissions from the user’s assigned custom role
  4. Team permissions — if any team the user belongs to grants the permission
  5. Default — falls back to the hardcoded default (typically false)

​
Default permissions

PermissionDefault (Worker)Description
can_view_all_jobsfalseView all jobs in the org, not just their own
can_view_billingfalseAccess billing and token usage pages
can_manage_usersfalseInvite, remove, and manage org members
can_download_correctionstrueDownload corrected files
can_delete_jobsfalseDelete analysis jobs
can_change_retentionfalseModify data retention settings
can_disable_gdprfalseDisable GDPR compliance checks

​
Team permissions

Teams have their own permission toggles that apply to all members. These are separate from the global permissions above and control team-specific behavior.
PermissionDefaultDescription
can_view_team_jobstrueMembers can see jobs created by other team members
can_download_correctionstrueMembers can download corrected files
can_disable_gdprfalseMembers can disable GDPR checks
can_change_retentionfalseMembers can change data retention settings
can_view_billingfalseMembers can view billing information
can_delete_jobsfalseMembers can delete jobs

​
Creating teams

Teams group users within your organisation. All team management requires admin access.
1

Navigate to Settings

Go to Settings > Teams in the web application.
2

Create a team

Click Create team and enter a name. Team names must be unique within your organisation.
3

Add members

Select users from your organisation to add to the team. Users can belong to multiple teams.
4

Configure permissions

Toggle the team permission switches to control what members can do.

​
Managing custom roles

Custom roles let you define reusable permission sets that can be assigned to individual users.
1

Create a role

Go to Settings > Roles and click Create role. Give it a name and optional description.
2

Set permissions

Toggle individual permissions on or off. Unset permissions fall back to the system default.
3

Assign to users

Assign the custom role to users. A user can have one custom role at a time.
You cannot delete a custom role while users are assigned to it. Reassign those users to a different role first.

​
Job visibility

Job access follows these rules:
  1. Admins can see all jobs in the organisation.
  2. Job creators can always see their own jobs.
  3. Users with can_view_all_jobs can see every job.
  4. Team members can see each other’s jobs if the team has can_view_team_jobs enabled.
If none of these conditions apply, the user cannot see the job.

​
API reference

All team and role endpoints require admin authentication. Base path: /api/v1.

​
Teams

MethodEndpointDescription
GET/teamsList all teams with member counts
POST/teamsCreate a team
GET/teams/{team_id}Get team with members and permissions
PATCH/teams/{team_id}Rename a team
DELETE/teams/{team_id}Delete a team and remove all members
POST/teams/{team_id}/membersAdd a user to a team
DELETE/teams/{team_id}/members/{user_id}Remove a user from a team
GET/teams/{team_id}/permissionsGet team permission toggles
PATCH/teams/{team_id}/permissionsUpdate team permissions

​
Roles

MethodEndpointDescription
GET/rolesList all roles (system + custom)
POST/rolesCreate a custom role
PATCH/roles/{role_id}Update a custom role
DELETE/roles/{role_id}Delete a custom role (must have no assigned users)

​
Example: create a team and set permissions

# Create a team
curl -X POST https://api.orca-klavest.app/api/v1/teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Data Engineering"}'

# Update team permissions
curl -X PATCH https://api.orca-klavest.app/api/v1/teams/{team_id}/permissions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "can_view_team_jobs": true,
      "can_delete_jobs": true,
      "can_download_corrections": true
    }
  }'