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

Advanced Operations

Upsert Role - POST /v1/workspaces/{workspaceId}/role/upsert

Create or update a role based on customer role ID (idempotent operation)

Common Use Cases

Initial Setup

Enable RBAC for your workspace
Create roles that match your organization's structure
Assign roles to taxonomies to control knowledge access
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. The upsert endpoint is particularly useful for keeping roles synchronized.

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

Current Limitation: There is currently no v1 API endpoint to check the status of these async operations when using API key authentication.

Workarounds:

Poll the role endpoints (GET, List, Find) to verify the operation completed
Treat operations as eventually consistent (typically complete within seconds)
Use GET /workspaces/{workspaceId}/role/status if you have user authentication credentials

Future v1 Endpoints (planned):

GET /v1/workspaces/{workspaceId}/workflows/{workflowId}/status - Check workflow status by ID
GET /v1/workspaces/{workspaceId}/background-jobs - List all background jobs
GET /v1/workspaces/{workspaceId}/background-jobs/{jobId} - Get specific job status

These endpoints will support API key authentication and return:

status: RUNNING, COMPLETED, FAILED, CANCELLED, etc.
progress: Operation progress percentage
result: Final result when completed
error: Error details if failed

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
409 Conflict - Role with the same customer role ID already exists
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 Operations

Use the upsert endpoint when you want to ensure a role exists with specific properties, regardless of whether it's already been created. This is particularly useful for:

Infrastructure-as-code deployments
Automated provisioning scripts
Synchronization with external systems

Role Lifecycle

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

Related APIs

Taxonomies API - Assign roles to taxonomies to control knowledge access
Spaces API - Generate role-bound tokens for users