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

Permission Format

Permissions follow the pattern resource:action:

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.