---
sidebar_position: 1
title: Roles & Permissions
description: Understanding team roles (member, leader, supervisor) and their permissions in the Firetell Call Center.
---

# Roles & Permissions

Every agent in a workspace has a **role** that determines what they can do. The Firetell Call Center uses a 3-tier role system.

## Roles

| Role | Description |
|---|---|
| **member** | Standard agent. Can make/receive calls, manage their own contacts, and view their own call history. |
| **leader** | Team lead. Has all member permissions plus team-wide visibility and agent management capabilities. |
| **supervisor** | Call center supervisor. Focuses on call quality assurance — real-time call supervision (listen, whisper, barge) plus team-wide visibility. |

## Permission Matrix

| Feature | `member` | `leader` | `supervisor` |
|---|:---:|:---:|:---:|
| **Basic Operations** | | | |
| View teams I belong to | ✅ | ✅ | ✅ |
| View teammates + presence | ✅ | ✅ | ✅ |
| CRUD my own contacts | ✅ | ✅ | ✅ |
| View contacts in accessible lists (personal, team, shared) | ✅ | ✅ | ✅ |
| Create / update / delete personal address books (`owner_type: agent`) | ✅ | ✅ | ✅ |
| View phone numbers (scoped by team) | ✅ | ✅ | ✅ |
| View my call history | ✅ | ✅ | ✅ |
| Transfer calls between agents | ✅ | ✅ | ✅ |
| **Team Management** | | | |
| Create / update / delete team address books (`owner_type: team`) | ❌ | ✅ | ❌ |
| Create / update / delete shared address books (`owner_type: everyone`) | ❌ | ✅ | ❌ |
| View team-wide call history | ❌ | ✅ | ✅ |
| View all team contacts | ❌ | ✅ | ✅ |
| Assign / remove agents from teams | ❌ | ✅ | ❌ |
| **Call Supervision** | | | |
| Silent listen (monitor) | ❌ | ❌ | ✅ |
| Whisper (coach agent) | ❌ | ❌ | ✅ |
| Barge-in (3-way call) | ❌ | ❌ | ✅ |

## Setting Roles

Roles are assigned when adding an agent to a team via the admin console or the Workspace API:

```bash
PUT /teams/:team_id/agents/:agent_id
```

```json
{
  "role": "leader"
}
```

Valid values: `member` (default), `leader`, `supervisor`.

An agent has a **single workspace-level role** that applies across all teams they belong to.
:::

## Endpoint Access by Role

### All Agents (member, leader, supervisor)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/call-center/teams` | List my teams |
| `GET` | `/call-center/teams/:id/agents` | List teammates |
| `GET` | `/call-center/contacts` | List contacts in my accessible lists |
| `POST` | `/call-center/contacts` | Create contact |
| `PUT` | `/call-center/contacts/:id` | Update contact |
| `DELETE` | `/call-center/contacts/:id` | Delete contact |
| `GET` | `/call-center/address-books` | List accessible address books |
| `GET` | `/call-center/address-books/:id` | Get address book details |
| `POST` | `/call-center/address-books` | Create personal address book (`owner_type: agent`) |
| `PUT` | `/call-center/address-books/:id` | Update personal address book |
| `DELETE` | `/call-center/address-books/:id` | Delete personal address book |
| `GET` | `/call-center/phone-numbers` | List phone numbers |
| `GET` | `/call-center/call-history` | List my calls |
| `POST` | `/call-center/calls/:call_id/transfer` | Transfer call |

### Leader Only

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/call-center/address-books` | Create team/shared address book (`owner_type: team` or `everyone`) |
| `PUT` | `/call-center/address-books/:id` | Update team/shared address book |
| `DELETE` | `/call-center/address-books/:id` | Delete team/shared address book |
| `GET` | `/call-center/teams/:team_id/call-history` | Team call history |
| `GET` | `/call-center/teams/:team_id/call-history/:id` | Team call details |
| `PUT` | `/call-center/teams/:id/agents/:agent_id` | Assign agent to team |
| `DELETE` | `/call-center/teams/:id/agents/:agent_id` | Remove agent from team |
| `GET` | `/call-center/teams/:team_id/contacts` | Team contacts |
| `GET` | `/call-center/teams/:team_id/agents/states` | Team agent states |
| `PUT` | `/call-center/teams/:team_id/agents/:username/state` | Force agent state |

### Leader & Supervisor

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/call-center/teams/:team_id/call-history` | Team call history |
| `GET` | `/call-center/teams/:team_id/call-history/:id` | Team call details |
| `GET` | `/call-center/teams/:team_id/agents/states` | Team agent states |
| `PUT` | `/call-center/teams/:team_id/agents/:username/state` | Force agent state |

### Supervisor Only

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/call-center/calls/:call_id/listen` | Silent monitor |
| `POST` | `/call-center/calls/:call_id/whisper` | Coach agent |
| `POST` | `/call-center/calls/:call_id/barge` | Join as 3-way call |
| `DELETE` | `/call-center/calls/:call_id/supervision` | Stop supervision |

## Error Responses

When an agent tries to access an endpoint they don't have permission for:

```json
{
  "statusCode": 403,
  "message": "This action requires one of the following roles: leader, supervisor",
  "error": "Forbidden"
}
```

When an agent tries to access a team they don't belong to:

```json
{
  "statusCode": 403,
  "message": "You are not a member of this team",
  "error": "Forbidden"
}
```