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

Users are members of your organization.
Roles are named collections of permissions (e.g., “Admin”, “Agent Builder”, “Viewer”).
Permissions are granular access rights (e.g., agents:write, billing:read).
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

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

Inviting Team Members

Go to Settings > Team > Invite.
Enter the email address.
Select a role.
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.

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

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

{
  "detail": "Permission denied: agents:write"
}

Checking Permissions

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

curl https://api.thinnest.ai/api/users/me \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"

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

Introduction

Getting Started

Voice Agents

Agent Capabilities

Channels

Quality & Oversight

Platform

Roles & Permissions

Roles & Permissions (RBAC)

How RBAC Works

Built-in Roles

Permission Format

Managing Roles

From the Dashboard

Inviting Team Members

Organizations & Projects

Organizations

Projects

Resource-Scoped Permissions

API Access with RBAC

Checking Permissions

Best Practices

​Roles & Permissions (RBAC)

​How RBAC Works

​Built-in Roles

​Permission Format

​Managing Roles

​From the Dashboard

​Inviting Team Members

​Organizations & Projects

​Organizations

​Projects

​Resource-Scoped Permissions

​API Access with RBAC

​Checking Permissions

​Best Practices

Roles & Permissions (RBAC)

How RBAC Works

Built-in Roles

Permission Format

Managing Roles

From the Dashboard

Inviting Team Members

Organizations & Projects

Organizations

Projects

Resource-Scoped Permissions

API Access with RBAC

Checking Permissions

Best Practices