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

# Teams & roles

> Who can see and do what: roles, the permission matrix, and how teams scope access to assessments and reports.

Your workspace has roles, an editable permission matrix, and optional teams. This page
explains the model so the API's `403` and `404` responses make sense.

<Note>
  Team and role management happens in the dashboard, not the API. `GET /v1/members` reads
  the roster; inviting teammates and editing permissions are dashboard actions.
</Note>

## Roles

| Role              | For                                 | Notes                                                                                                                |
| ----------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Company Admin** | Owners and engineering leads        | Full access. Also the only role that can manage billing, branding, API keys, users, teams and the permission matrix. |
| **Developer**     | Engineers running technical screens | Creates assessments and reviews work by default.                                                                     |
| **Recruiter**     | Talent partners                     | Invites candidates and reads reports by default; doesn't create assessments.                                         |

Every workspace keeps at least one Company Admin — the last one can't be demoted or
removed.

## The permission matrix

Four toggles. Admins can change the Developer and Recruiter columns from **Settings → User
roles**; the Admin column is fixed.

| Permission                    | Company Admin | Developer (default) | Recruiter (default) |
| ----------------------------- | ------------- | ------------------- | ------------------- |
| Create assessments            | ✓             | ✓                   | ✗                   |
| Team-shared assessments       | edit          | edit                | view                |
| Team-shared candidate reports | edit          | view                | edit                |
| Invite candidates             | ✓             | ✓                   | ✓                   |

These are only the defaults — your workspace may have customized them, so check
**Settings → User roles** for what's actually enabled. Customizations are stored as a diff
from the defaults, so a workspace that never changes them picks up improvements
automatically.

## How teams scope access

A team groups members. Teams are **opt-in**: a workspace with no teams behaves as if
everyone can see everything their role allows.

Once teams exist, a non-admin can reach an assessment or report when **any** of these holds:

<Steps>
  <Step title="They created it">
    Your own work is always yours.
  </Step>

  <Step title="They share a team with the creator">
    …and their role's shared-access level permits it.
  </Step>

  <Step title="The creator is on no team">
    Unassigned work stays visible workspace-wide, so putting one person on a team doesn't
    hide everyone else's work.
  </Step>
</Steps>

Sharing is **computed, not stored** — content is shared "within the creator's teams", so
moving someone between teams re-scopes their work immediately.

## What this means for the API

An API key inherits the role of the member who created it. A key created by a Recruiter
carries Recruiter permissions.

<Warning>
  Scope and permission are two different gates, and both apply. A `write`-scoped key created
  by a Recruiter gets `403` on `POST /v1/assessments` — the scope allows writes, the role
  doesn't allow that particular one.
</Warning>

How the failures look:

| Situation                                | Response                                         |
| ---------------------------------------- | ------------------------------------------------ |
| Key lacks the scope                      | `403 INSUFFICIENT_SCOPE`                         |
| Role can't perform the action            | `403`                                            |
| Content exists but team scoping hides it | `404 NOT_FOUND` — identical to absent, by design |

<Tip>
  For an integration that should see everything in the workspace, have a Company Admin
  create the key. A key made by a team-scoped member sees only what that member sees, which
  is usually a surprise when a nightly export quietly returns fewer rows than expected.
</Tip>