Teams & Permissions

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.

Role	Access level	Modifiable
Admin	Full access to all features, settings, billing, and team management	No
Worker	Default permission set (see table below)	No
Custom roles	Admin-defined permission sets assigned to individual users	Yes

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:

Admin role — always granted
Explicit user permission — per-user override (if set)
Custom role — permissions from the user’s assigned custom role
Team permissions — if any team the user belongs to grants the permission
Default — falls back to the hardcoded default (typically false)

Default permissions

Permission	Default (Worker)	Description
`can_view_all_jobs`	false	View all jobs in the org, not just their own
`can_view_billing`	false	Access billing and token usage pages
`can_manage_users`	false	Invite, remove, and manage org members
`can_download_corrections`	true	Download corrected files
`can_delete_jobs`	false	Delete analysis jobs
`can_change_retention`	false	Modify data retention settings
`can_disable_gdpr`	false	Disable 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.

Permission	Default	Description
`can_view_team_jobs`	true	Members can see jobs created by other team members
`can_download_corrections`	true	Members can download corrected files
`can_disable_gdpr`	false	Members can disable GDPR checks
`can_change_retention`	false	Members can change data retention settings
`can_view_billing`	false	Members can view billing information
`can_delete_jobs`	false	Members can delete jobs

Creating teams

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

Navigate to Settings

Go to Settings > Teams in the web application.

Create a team

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

Add members

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

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.

Create a role

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

Set permissions

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

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:

Admins can see all jobs in the organisation.
Job creators can always see their own jobs.
Users with can_view_all_jobs can see every job.
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

Method	Endpoint	Description
`GET`	`/teams`	List all teams with member counts
`POST`	`/teams`	Create 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}/members`	Add a user to a team
`DELETE`	`/teams/{team_id}/members/{user_id}`	Remove a user from a team
`GET`	`/teams/{team_id}/permissions`	Get team permission toggles
`PATCH`	`/teams/{team_id}/permissions`	Update team permissions

Roles

Method	Endpoint	Description
`GET`	`/roles`	List all roles (system + custom)
`POST`	`/roles`	Create 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
    }
  }'

Getting started

Features

Administration

Integrations

Security & compliance

Developer Tools

Methodology

Overview

Role hierarchy

Permission resolution order

Default permissions

Team permissions

Creating teams

Managing custom roles

Job visibility

API reference

Teams

Roles

Example: create a team and set permissions

​Overview

​Role hierarchy

​Permission resolution order

​Default permissions

​Team permissions

​Creating teams

​Managing custom roles

​Job visibility

​API reference

​Teams

​Roles

​Example: create a team and set permissions

Overview

Role hierarchy

Permission resolution order

Default permissions

Team permissions

Creating teams

Managing custom roles

Job visibility

API reference

Teams

Roles

Example: create a team and set permissions