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

# Roles & Permissions

> Control access to your agents, data, and platform features with role-based access control (RBAC).

# Roles & Permissions (RBAC)

thinnestAI uses **Role-Based Access Control** (RBAC) to manage who can do what on your platform. Assign roles to team members, and each role grants specific permissions for agents, billing, knowledge, and more.

## How RBAC Works

```
User → assigned Role(s) → Role has Permissions → Permissions control access
```

1. **Users** are members of your organization.
2. **Roles** are named collections of permissions (e.g., "Admin", "Agent Builder", "Viewer").
3. **Permissions** are granular access rights (e.g., `agents:write`, `billing:read`).
4. When a user makes a request, the system checks if their role(s) include the required permission.

## Built-in Roles

| Role              | Description                                                               | Typical Permissions                                                              |
| ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Owner**         | Full platform access. Can manage billing, team members, and all settings. | All permissions                                                                  |
| **Admin**         | Manage agents, knowledge, and team members. Cannot change billing.        | `agents:*`, `knowledge:*`, `teams:*`, `users:read`                               |
| **Agent Builder** | Create and configure agents. Cannot manage team or billing.               | `agents:read`, `agents:write`, `knowledge:read`, `knowledge:write`, `tools:read` |
| **Viewer**        | Read-only access to agents, analytics, and call logs.                     | `agents:read`, `analytics:read`, `sessions:read`                                 |

## Permission Format

Permissions follow the pattern `resource:action`:

| Permission        | Description                                 |
| ----------------- | ------------------------------------------- |
| `agents:read`     | View agent configurations and settings      |
| `agents:write`    | Create, update, and delete agents           |
| `agents:deploy`   | Deploy agents and assign phone numbers      |
| `knowledge:read`  | View knowledge sources                      |
| `knowledge:write` | Create and update knowledge sources         |
| `billing:read`    | View billing information and usage          |
| `billing:write`   | Manage payments, top-ups, and subscriptions |
| `teams:read`      | View team members                           |
| `teams:write`     | Invite, remove, and change member roles     |
| `sessions:read`   | View conversation history and call logs     |
| `analytics:read`  | View dashboards and performance metrics     |
| `campaigns:read`  | View campaigns                              |
| `campaigns:write` | Create, run, and manage campaigns           |
| `tools:read`      | View tool configurations                    |
| `tools:write`     | Configure tool credentials and settings     |

## Managing Roles

### From the Dashboard

1. Navigate to **Settings > Team**.
2. Click on a team member to view their role.
3. Use the role dropdown to change their role.
4. Changes take effect immediately.

### Inviting Team Members

1. Go to **Settings > Team > Invite**.
2. Enter the email address.
3. Select a role.
4. Click **Send Invitation**.

The invitee receives an email to join your organization with the assigned role.

## Organizations & Projects

RBAC integrates with the organization and project structure:

### Organizations

An **organization** is the top-level container for your team. All agents, knowledge, and billing belong to an organization.

```bash theme={null}
# List organization members
curl https://api.thinnest.ai/api/organizations/members \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

### Projects

**Projects** are subgroups within an organization for organizing work:

```bash theme={null}
# Create a project
curl -X POST https://api.thinnest.ai/api/projects \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agents",
    "description": "All customer-facing support agents"
  }'
```

Project members can have different roles than their organization role, allowing fine-grained access control per project.

## Resource-Scoped Permissions

Permissions can be scoped to specific resources:

* **Organization-wide** — Access to all resources in the org (default)
* **Project-scoped** — Access only to resources within a specific project
* **Agent-scoped** — Access only to a specific agent

Example: A contractor might have `agents:write` scoped to a single project, not the entire organization.

## API Access with RBAC

All API endpoints enforce RBAC. If a user's token doesn't have the required permission, the API returns `403 Forbidden`:

```json theme={null}
{
  "detail": "Permission denied: agents:write"
}
```

### Checking Permissions

The current user's permissions are included in their profile:

```bash theme={null}
curl https://api.thinnest.ai/api/users/me \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "user_id": "auth0|abc123",
  "email": "user@example.com",
  "roles": ["agent_builder"],
  "permissions": ["agents:read", "agents:write", "knowledge:read", "knowledge:write"]
}
```

## Best Practices

* **Principle of least privilege** — Give users the minimum permissions they need.
* **Use Viewer role for stakeholders** — Business users who need to see analytics but not change configs.
* **Use Agent Builder for developers** — Can build and test without access to billing or team management.
* **Regularly audit roles** — Review who has what access, especially after team changes.
* **Use projects for isolation** — Separate client work or departments into projects with scoped access.