Skip to main content

​
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

RoleDescriptionTypical Permissions
OwnerFull platform access. Can manage billing, team members, and all settings.All permissions
AdminManage agents, knowledge, and team members. Cannot change billing.agents:*, knowledge:*, teams:*, users:read
Agent BuilderCreate and configure agents. Cannot manage team or billing.agents:read, agents:write, knowledge:read, knowledge:write, tools:read
ViewerRead-only access to agents, analytics, and call logs.agents:read, analytics:read, sessions:read

​
Permission Format

Permissions follow the pattern resource:action:
PermissionDescription
agents:readView agent configurations and settings
agents:writeCreate, update, and delete agents
agents:deployDeploy agents and assign phone numbers
knowledge:readView knowledge sources
knowledge:writeCreate and update knowledge sources
billing:readView billing information and usage
billing:writeManage payments, top-ups, and subscriptions
teams:readView team members
teams:writeInvite, remove, and change member roles
sessions:readView conversation history and call logs
analytics:readView dashboards and performance metrics
campaigns:readView campaigns
campaigns:writeCreate, run, and manage campaigns
tools:readView tool configurations
tools:writeConfigure 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. 
# 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.