> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca-klavest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Teams & Permissions

> Set up teams, assign roles, and manage granular permissions for your organisation.

## 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:

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

| 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.

<Steps>
  <Step title="Navigate to Settings">
    Go to **Settings > Teams** in the web application.
  </Step>

  <Step title="Create a team">
    Click **Create team** and enter a name. Team names must be unique within your organisation.
  </Step>

  <Step title="Add members">
    Select users from your organisation to add to the team. Users can belong to multiple teams.
  </Step>

  <Step title="Configure permissions">
    Toggle the team permission switches to control what members can do.
  </Step>
</Steps>

## Managing custom roles

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

<Steps>
  <Step title="Create a role">
    Go to **Settings > Roles** and click **Create role**. Give it a name and optional description.
  </Step>

  <Step title="Set permissions">
    Toggle individual permissions on or off. Unset permissions fall back to the system default.
  </Step>

  <Step title="Assign to users">
    Assign the custom role to users. A user can have one custom role at a time.
  </Step>
</Steps>

<Warning>
  You cannot delete a custom role while users are assigned to it. Reassign those users to a different role first.
</Warning>

## 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

| 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

```bash theme={null}
# 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
    }
  }'
```