Roles in Sharely.ai

Sharely.ai uses different types of roles to control access, permissions, and collaboration across the platform. Understanding these role types is essential for effectively managing your workspace and enabling the right people to access the right content.

Three Types of Roles

Sharely.ai has three distinct role systems, each serving a different purpose:

Workspace Roles

Workspace roles control who can manage and administer your Sharely.ai workspace. These roles determine platform access and administrative capabilities.

Available Workspace Roles

When to Use Workspace Roles

• Admins: Your core team members who set up and maintain the AI assistant, manage knowledge, and configure the workspace
• Hosts: Team members (sales reps, support agents) who need to create and manage spaces with customers but shouldn't modify global settings
• Members: Team members who need visibility into workspace content for collaboration purposes but shouldn't create or modify resources (e.g., observers, analysts, stakeholders)

Managing Workspace Roles

Workspace roles are assigned when you invite team members to your workspace:

1. Navigate to Workspace Settings → Team Members
2. Click "Invite Team Member"
3. Enter email address
4. Select role: Admin, Host, or Member
5. Send invitation

Space Roles

Space roles define who participates in conversations within individual spaces. These roles enable collaboration between your team and customers.

Available Space Roles

Space Role Workflow

Typical engagement flow:

1. Host creates a space for a customer/prospect
2. Guest is invited to the space (becomes the customer)
3. Co-hosts can be added to support the engagement
4. Everyone collaborates with the AI assistant and each other
5. Space persists with full conversation history

When to Use Space Roles

• Guest: Your customers, prospects, or anyone you're engaging with
• Host: Account owner, sales rep, or primary contact for the customer
• Co-host: Technical support, specialists, or team members helping with the engagement

Knowledge Roles (RBAC)

Knowledge Roles provide Role-Based Access Control (RBAC) to control which users can access which knowledge items. This is essential for multi-tenant applications, tiered content access, or enterprise security.

What Are Knowledge Roles?

Knowledge Roles allow you to:

• ✅ Control content access - Assign knowledge items to specific roles
• ✅ Filter search results - Users only see knowledge they're permitted to access
• ✅ Scope API responses - All knowledge and taxonomy APIs automatically filter by role
• ✅ Enable multi-tenancy - Different customers see different content
• ✅ Implement tiered access - Premium users see premium content

How Knowledge Roles Work

1. Create Role → 2. Assign Knowledge to Role → 3. Assign Role to User → 4. User Gets Filtered Content

Example Scenario:

// Three roles with different content access
Roles:
  - "premium-subscriber" → Access to all premium articles + basic articles
  - "basic-subscriber" → Access to basic articles only
  - "trial-user" → Access to sample articles only
 
Knowledge Assignment:
  - Premium Article #1 → Assigned to "premium-subscriber"
  - Premium Article #2 → Assigned to "premium-subscriber"
  - Basic Article #1 → Assigned to "premium-subscriber", "basic-subscriber"
  - Sample Article #1 → Assigned to all roles
 
User Experience:
  - Premium User searches → Sees premium + basic + sample articles
  - Basic User searches → Sees basic + sample articles only
  - Trial User searches → Sees sample articles only

Creating Knowledge Roles

Method 1: Using Customer Role ID (Recommended)

Create roles with your own identifiers - no UUID mapping needed:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/roles' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "premium-subscriber",
    "name": "Premium Subscriber",
    "description": "Access to all premium content and features"
  }'

Method 2: Using UUID

Let Sharely generate a UUID for the role:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/roles' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Premium Subscriber",
    "description": "Access to all premium content and features"
  }'

Assigning Knowledge to Roles

Once roles are created, assign knowledge items to them:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledge/{knowledgeId}/role' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "roleIds": ["role-uuid-1", "role-uuid-2"]
  }'

Assigning Roles to Users

When creating user tokens, include the role:

# Step 1: Generate API token with role
curl -X POST \
  'https://api.sharely.ai/workspaces/{workspaceId}/generate-access-key-token' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "premium-subscriber"
  }'
 
# Step 2: Create user space (role inherited automatically)
curl -X PUT \
  'https://api.sharely.ai/workspaces/{workspaceId}/activate-or-retrieve-user-space' \
  -H 'Authorization: Bearer {token-from-step-1}' \
  -H 'organizationId: {organizationId}' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceId": "{workspaceId}",
    "customerIdString": "user@example.com"
  }'

The role is now embedded in the user's token, and all subsequent API calls will automatically filter content based on that role.

When to Use Knowledge Roles

Common Use Cases:

1. Multi-tenant SaaS Applications

   • Each customer organization sees only their content
   • "customer-acme", "customer-globex", etc.

2. Tiered Subscription Models

   • "free-tier" → Limited content
   • "pro-tier" → Enhanced content
   • "enterprise-tier" → Full access

3. Department-Based Access

   • "sales-team" → Sales materials and pricing
   • "support-team" → Support documentation
   • "engineering-team" → Technical specs

4. Compliance and Security

   • "public-content" → Unrestricted
   • "internal-only" → Employee access
   • "confidential" → Senior leadership only

5. Partner/Customer Portals

   • "partner-tier-gold" → Premium partner content
   • "partner-tier-silver" → Standard partner content
   • "customer-portal" → Customer-facing documentation

Role Comparison Matrix

Combining Role Types

Different role types work together to create a complete access control system:

Example: SaaS Application with Customer Support

Workspace Setup:

• Admin (You) - Configures the workspace, manages knowledge, sets up RBAC
• Host (Support Reps) - Creates support spaces for customers

Space Engagement:

• Guest (Customer) - Accesses their support space
• Host (Assigned Support Rep) - Primary contact for the customer
• Co-host (Senior Support Engineer) - Helps with complex issues

Knowledge Access:

• Customer token assigned "customer-basic" role → Sees public documentation
• Support Rep token assigned "support-team" role → Sees public + internal knowledge
• Senior Engineer token assigned "engineering-team" role → Sees all technical content

Result:

• Support reps can create spaces (Workspace Role)
• Customers engage in their spaces (Space Role)
• Everyone sees appropriate content (Knowledge Role)

Best Practices

Workspace Roles

• ✅ Limit Admin access to core team members who manage the platform
• ✅ Use Host role for customer-facing team members
• ✅ Regularly review team access and remove inactive users
• ✅ Use email verification for team invitations

Space Roles

• ✅ Assign a dedicated Host for each customer space
• ✅ Add Co-hosts only when needed to keep conversations focused
• ✅ Use guest invitations to bring in additional stakeholders
• ✅ Archive inactive spaces to keep workspace organized

Knowledge Roles (RBAC)

• ✅ Use customerRoleId (custom strings) instead of UUIDs for easier management
• ✅ Create role hierarchy: basic → standard → premium → enterprise
• ✅ Assign knowledge to multiple roles when content applies broadly
• ✅ Test role filtering with different user tokens before production
• ✅ Document your role structure and what each role can access
• ✅ Use descriptive role names: "sales-manager" instead of "role-1"

Related Documentation

Workspace Roles

• Workspace Concept - Learn about workspaces
• UX Views - Workspace View - Workspace management UI

Space Roles

• Space Concept - Learn about spaces
• UX Views - Host View - Host and space management UI
• UX Views - My Spaces - Guest space access

Knowledge Roles (RBAC)

• Roles API - Create and manage roles via API
• Knowledge Roles API - Assign knowledge to roles
• Spaces API - Role-Bound Tokens - Implementing RBAC in your application
• Authentication - API authentication overview

Frequently Asked Questions

Q: Can a user have multiple roles?

A: Currently, each user token has one Knowledge Role at a time. However:

• A team member can be both a Workspace Admin and a Space Host
• A user can be a Guest in multiple spaces simultaneously
• A user's Knowledge Role can be changed by generating a new token

Q: What happens if I don't assign any Knowledge Roles to my knowledge items?

A: If RBAC is disabled, all users see all knowledge. If RBAC is enabled but knowledge has no roles assigned, only users without a specific role can see it (or it may be inaccessible depending on configuration). Always assign roles to knowledge items when using RBAC.

Q: Can I change a user's Knowledge Role without creating a new token?

A: No. Knowledge Roles are embedded in the JWT token. To change a user's role, you must generate a new token with the new role and update the user's session.

Q: Do Space Roles affect Knowledge visibility?

A: No. Space Roles (Guest, Host, Co-host) control who can participate in a space conversation. Knowledge Roles control which knowledge items a user can access. These are independent systems.

Q: Can I use the same role name for different purposes?

A: Technically yes, but it's not recommended. For clarity, use distinct naming:

• Knowledge Roles: "premium-tier", "sales-team"
• Workspace Roles: Use built-in Admin/Host roles
• Space Roles: Use built-in Guest/Host/Co-host roles

Q: How do I migrate existing users to RBAC?

A:

1. Enable RBAC on your workspace
2. Create Knowledge Roles for your user segments
3. Assign existing knowledge items to appropriate roles
4. Update your authentication flow to include customerRoleId when generating tokens
5. Gradually roll out to users by updating their tokens upon next login

Getting Started

1. Understand your needs: Determine which role types you need

   • Managing a team? → Workspace Roles
   • Engaging customers? → Space Roles
   • Controlling content access? → Knowledge Roles

2. Set up Workspace Roles first: Invite your team members with appropriate roles

3. Configure Knowledge Roles (if needed):

   • Enable RBAC on your workspace
   • Create roles via Roles API
   • Assign knowledge to roles

4. Create Spaces: Use Space Roles to engage with customers

5. Test thoroughly: Verify that each role type works as expected before going to production