Roles API

The Roles API allows you to manage Role-Based Access Control (RBAC) in your Sharely.ai workspace. Roles enable you to control which users can access specific knowledge and taxonomies.

Overview

Roles are the foundation of Sharely.ai's RBAC system. Each role represents a set of permissions that can be assigned to users, controlling their access to knowledge items and taxonomies. Roles can be identified either by Sharely's internal UUID or by your own customer-provided role identifiers.

Key Concepts

Role Identifiers

Each role has two types of identifiers:

  • roleId (UUID): Sharely's internal unique identifier, automatically generated
  • customerRoleId (string): Your custom identifier (e.g., "sales-manager", "admin-role")

The customerRoleId is particularly useful for integrating with your existing systems, as it allows you to reference roles using your own naming conventions.

RBAC Status

Before using roles, you must enable RBAC for your workspace:

curl -X PUT \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/rbac-status' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "rbacEnabled": true
  }'

Authentication

All Role API endpoints require Bearer token authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

See the Authentication guide for details on obtaining and managing API keys.

Base URL

All Role API endpoints use the following base URL pattern:

https://api.sharely.ai/v1/workspaces/{workspaceId}/role

Replace {workspaceId} with your actual workspace ID.

Available Endpoints

Role Management

  • List Roles - GET /v1/workspaces/{workspaceId}/role

    Retrieve all roles in your workspace

  • Create Role - POST /v1/workspaces/{workspaceId}/role

    Create a new role with a name and optional description

  • Get Role - GET /v1/workspaces/{workspaceId}/role/{roleId}

    Retrieve a specific role by its UUID

  • Update Role - PUT /v1/workspaces/{workspaceId}/role/{roleId}

    Update an existing role's properties

  • Delete Role - DELETE /v1/workspaces/{workspaceId}/role/{roleId}

    Delete a role (async operation)

Role Queries

  • Find Roles - POST /v1/workspaces/{workspaceId}/role/find

    Search for roles by customer role ID or name

  • Get by Customer Role ID - GET /v1/workspaces/{workspaceId}/role/by-customer-role-id/{customerRoleId}

    Retrieve a role using your custom identifier

Common Use Cases

Initial Setup

  1. Enable RBAC for your workspace
  2. Create roles that match your organization's structure
  3. Assign roles to taxonomies to control knowledge access
  4. Generate role-bound tokens for users

Integration Patterns

Syncing with External Systems: Use the customerRoleId field to map your existing role identifiers to Sharely roles. Use Get by Customer Role ID to check whether a role exists before creating it, keeping sync scripts idempotent.

Dynamic Role Creation: Create roles on-the-fly as users are provisioned in your system, using the create endpoint with customer role IDs.

Lookup Operations: Use the find or get-by-customer-role-id endpoints to retrieve role information when you only have your custom identifier.

Asynchronous Operations

Role creation, updates, and deletions are asynchronous operations. When you make these requests, the API returns a workflow ID:

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000"
}

Checking Workflow Status

Use the Background Jobs endpoint to check the status of async operations with API key authentication:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/background-jobs' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{ "jobIds": ["550e8400-e29b-41d4-a716-446655440000"] }'

It returns each job's workflow status (RUNNING, COMPLETED, FAILED, …). You can also simply poll the role endpoints (GET, List, Find) to verify the operation completed — operations are eventually consistent and typically complete within seconds.

Error Handling

Common error responses you may encounter:

  • 400 Bad Request - Invalid request parameters or missing required fields
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Role or workspace not found
  • 500 Internal Server Error - Server error during processing

See the Error Reference for more details.

Best Practices

Naming Conventions

  • Use clear, descriptive names for roles (e.g., "Sales Manager", "Content Editor")
  • Use consistent naming patterns for customer role IDs (e.g., lowercase-with-hyphens)
  • Include descriptions to document the purpose of each role

Customer Role IDs

  • Choose stable identifiers that won't change over time
  • Use identifiers that match your existing systems for easier integration
  • Keep them simple and human-readable (e.g., "sales-team", "admin", "viewer")

Idempotent Provisioning

When you want to ensure a role exists with specific properties — for infrastructure-as-code deployments, automated provisioning scripts, or synchronization with external systems — look the role up by customerRoleId first, then create or update accordingly:

  1. GET /v1/workspaces/{workspaceId}/role/by-customer-role-id/{customerRoleId}
  2. If 404: create the role with that customerRoleId
  3. If found and properties differ: update it

Role Lifecycle

  1. Create: Use specific customer role IDs during creation
  2. Query: Use find or get-by-customer-role-id for lookups
  3. Update: Modify role properties as your needs change
  4. Delete: Clean up unused roles, but be aware this is async

Related APIs

  • Taxonomy API - Assign roles to taxonomies to control knowledge access
  • Spaces API - Generate role-bound tokens for users
  • Agent API - Role-scoped threads and RAG for custom agents

Next Steps

  1. Enable RBAC for your workspace
  2. Create your first role
  3. Assign roles to taxonomies
  4. Generate role-bound tokens

Additional Resources