Roles and Permissions

Overview

Treblle’s Roles and Permissions system allows you to create custom roles with specific permissions tailored to your organization’s needs. Unlike the previous system with only Member and Owner roles, this new implementation offers:

• Granular Permissions: Fine-grained control over what users can access and modify
• Custom Roles: Create unlimited roles with specific permission combinations
• Per-API Access Control: Roles are assigned per API with environment-specific restrictions
• Environment-Specific Roles: Assign roles to specific environments (Production, Staging, Development)

Key Concepts

Roles

A role is a collection of permissions that can be assigned to users. Roles define what actions users can perform within your workspace and APIs.

Default Roles:

• Owner: Full access to all workspace and API features
• Member: Standard access with limited administrative capabilities

Both default roles can be customized to fit your needs.

Permissions

Permissions are specific actions or access rights grouped into two main categories:

Workspace Level Permissions

• Billing management
• Catalog access
• Workspace settings
• User management

API Level Permissions

• Request viewing and management
• Endpoint configuration
• API settings
• Integration management

Understanding Role Types

Treblle supports three main role types visible in the roles list:

1. Owner Role

• Full administrative access to all workspace features
• Can manage billing, users, and all APIs
• Typically assigned to workspace administrators and team leads
• Cannot be deleted as it’s a system role
• Default permission count: 33 permissions

2. Member Role

• Standard team member access
• Can view and work with APIs they have access to
• Limited administrative capabilities
• Default permission count: 14 permissions
• Most common role for development team members

3. Customer Role

Documentation Access (Scoped to Relevant APIs):

• Full endpoint specifications for APIs with their customer ID
• Authentication methods and requirements
• Request/response schemas and validation
• Code examples and integration guides
• OpenAPI specifications
• Interactive API documentation

Usage Data Access (Filtered):

• Request history (their customer ID only)
• Performance metrics (their requests only)
• Error logs (their errors only)
• Usage analytics (their consumption only)
• Device and location data (their requests only)

Dashboard & Analytics:

• Real-time performance dashboard
• Request volume and trend analytics
• Error rate monitoring and visualization
• Response time tracking
• Custom time period filtering

Key Characteristics:

• Automatic Discovery: APIs become visible when first request with customer ID arrives
• Dynamic Updates: Access updates automatically as customer ID appears in new APIs
• Self-Service: Customers can monitor their usage and debug integrations
• Privacy-First: Customers cannot see any data from other customers
• Scoped Documentation: Only see docs for APIs they actually use
• No Manual Configuration: Access is granted automatically based on API usage

What Customers Cannot See:

• APIs where their customer ID has never appeared
• Other customers’ request data or usage patterns
• Workspace-wide metrics or analytics
• Internal performance benchmarks

Implementation Requirements:

1. Customer ID must be passed in the treblle-metadata header:

   req.headers['treblle-metadata'] = JSON.stringify({
     'user-id': 'Netflix' // Must be globally unique
   });

2. Customer must be invited with the Customer role
3. Customer ID must be globally unique across your workspace
4. Customer ID in invitation should match the ID used in API requests
5. API documentation should be complete and accurate for customer reference

How Roles Work

• Per-API Assignment: Roles are assigned per API. When a user is given access to an API, they are assigned a specific role for that API with optional environment restrictions
• Consistent Permissions: Users maintain the same role permissions on each API they access, but can have different roles across different APIs
• API Access Required: Having a role doesn’t automatically grant API access - users must be added to APIs via API Access

Managing Roles

Viewing Roles

Navigate to User Management > Roles to view all roles in your workspace.

The Roles table displays:

Role Actions:

Each role in the table includes an actions menu (•••) providing quick access to:

• View Role: Opens the detailed role view showing all permissions and assigned users
• Delete: Removes the role from the workspace (only available if no users are currently assigned to the role)

Creating a New Role

1. Click + New Role in the Roles page
2. Fill in the role details:
   • Role Name: Enter a descriptive name (required)
   • Environment: Select one or more environments where this role applies
3. Select permissions:
   • Expand Workspace Settings to view and select workspace-level permissions
   • Expand API Level Access to view and select API-level permissions
   • Permissions are organized by category for easy navigation
4. Click Create Role

Environment-Specific Roles

Roles can be assigned to specific environments to control access based on deployment stage:

• Production: Live production environment
• Staging: Pre-production testing environment
• Development: Development and testing environment
• All: Role applies to all environments

Note

Customer Role Toggle: When enabled, this designates the role for external users. Customer roles typically have limited, read-only permissions and are designed for clients who need visibility into their API usage without administrative access.

Permission Categories:

Workspace Permissions

API Permissions

User Management and Security Permissions

Editing a Role

1. Click the ••• menu next to the role
2. Select Edit
3. Update the role name, environment, or permissions
4. Click Save

Viewing Role Details

To view comprehensive information about a specific role, click on the role name in the Roles table. This opens the role detail view.

The role detail view includes:

Header Information:

• Role Name: Displayed prominently at the top
• Environment Assignment: Shows which environments this role applies to (e.g., “None” means all environments)
• People Count: Number of users currently assigned to this role
• Action Buttons:
  • “Edit Role & Permissions” - Modify the role
  • “Delete” - Remove the role (if no users assigned)

Deleting a Role

To delete a role:

1. Ensure no users are assigned to the role (check the People column)
2. Click the ••• menu next to the role
3. Select Delete
4. Type DELETE to confirm
5. Click Delete Role