Create Role

Create a new role in your workspace. Roles are used to control access to knowledge and taxonomies through Sharely's RBAC system.

Endpoint

POST /v1/workspaces/{workspaceId}/role

Authentication

Requires Bearer token authentication. See Authentication for details on obtaining an access token.

Authorization: Bearer YOUR_ACCESS_TOKEN

Path Parameters

Request Body

Field Details

name (required):

• The human-readable name that will be displayed in the UI
• Should be clear and descriptive (e.g., "Sales Manager", "Content Editor")
• Maximum length: 255 characters

description (optional):

• Helps document the role's intended purpose and permissions
• Useful for team collaboration and future reference
• Maximum length: 1000 characters

customerRoleId (optional but recommended):

• Your own custom identifier for integration with external systems
• Must be unique within the workspace
• Use consistent naming patterns (e.g., "sales-manager", "content-editor")
• Alphanumeric characters and hyphens recommended
• Maximum length: 255 characters

Response

Success Response

Status Code: 201 Created

Headers:

X-API-Version: v1

Body:

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "role": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Sales Manager",
    "description": "Access to sales-related content",
    "customerRoleId": "sales-manager",
    "createdAt": "2025-11-11T10:00:00Z",
    "updatedAt": "2025-11-11T10:00:00Z"
  }
}

Examples

Create with Customer Role ID

Create a role with all fields specified:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "name": "Sales Manager",
    "description": "Access to sales-related knowledge and product information",
    "customerRoleId": "sales-manager"
  }'

Response:

{
  "workflowId": "789e0123-f45a-67b8-c901-234567890def",
  "role": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Sales Manager",
    "description": "Access to sales-related knowledge and product information",
    "customerRoleId": "sales-manager",
    "createdAt": "2025-11-11T14:30:00Z",
    "updatedAt": "2025-11-11T14:30:00Z"
  }
}

Create with Minimal Fields

Create a role with only the required name field:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Basic User"
  }'

Response:

{
  "workflowId": "456e7890-a12b-34c5-d678-901234567890",
  "role": {
    "id": "987fcdeb-51a2-43f7-b8c9-123456789abc",
    "name": "Basic User",
    "description": null,
    "customerRoleId": null,
    "createdAt": "2025-11-11T14:35:00Z",
    "updatedAt": "2025-11-11T14:35:00Z"
  }
}

Create Multiple Roles

Create several roles for your organization:

# Administrator role
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Administrator",
    "description": "Full access to all resources",
    "customerRoleId": "admin"
  }'
 
# Content Editor role
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Content Editor",
    "description": "Can create and edit content",
    "customerRoleId": "content-editor"
  }'
 
# Viewer role
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Viewer",
    "description": "Read-only access",
    "customerRoleId": "viewer"
  }'

Error Responses

400 Bad Request

Missing required field or invalid request:

{
  "error": "Bad Request",
  "message": "Missing required field: name"
}

Common causes:

• Missing name field
• Invalid field types
• Field values exceed maximum length

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Insufficient permissions:

{
  "error": "Forbidden",
  "message": "Insufficient permissions for this workspace"
}

409 Conflict

Role with the same customer role ID already exists:

{
  "error": "Conflict",
  "message": "Role with customerRoleId 'sales-manager' already exists"
}

500 Internal Server Error

Server error during processing:

{
  "error": "Internal Server Error",
  "message": "Failed to create role",
  "errorId": "550e8400-e29b-41d4-a716-446655440000"
}

Notes

Asynchronous Processing

Role creation is an asynchronous operation. The API returns immediately with a workflowId.

In most cases, the role is created instantly, but the async pattern allows for:

• Complex validation
• Integration with external systems
• Handling high-volume requests

Customer Role ID Uniqueness

If you provide a customerRoleId, it must be unique within the workspace. If a role with the same customerRoleId already exists, the request will fail with a 409 Conflict error.

To update an existing role instead, use the Update Role or Upsert Role endpoint.

RBAC Must Be Enabled

Before roles can be used to control access, you must enable RBAC for your workspace:

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

Role Assignment

After creating a role, you'll need to:

1. Assign it to taxonomies to control knowledge access
2. Generate role-bound tokens for users with that role
3. Configure which knowledge items are accessible to the role

See the Taxonomies API for details on role assignment.

Best Practices

Use Customer Role IDs

Always provide a customerRoleId when creating roles. This makes it easier to:

• Integrate with existing identity systems
• Reference roles in your application code
• Synchronize roles across environments

Descriptive Names and Descriptions

Use clear, descriptive names that reflect the role's purpose. Add descriptions to document:

• What access the role provides
• Which departments or teams use it
• Any special considerations or limitations

Consistent Naming Patterns

Establish a consistent naming pattern for customerRoleId values:

• Use lowercase with hyphens: sales-manager, content-editor
• Or use dot notation: sales.manager, content.editor
• Avoid spaces and special characters

Plan Your Role Hierarchy

Before creating roles, plan your access control structure:

• Identify distinct user groups and their access needs
• Create the minimum number of roles necessary
• Document what each role can access

Related Endpoints

• List Roles - View all existing roles
• Update Role - Modify role properties
• Upsert Role - Create or update idempotently
• Get by Customer Role ID - Look up by custom ID

Next Steps

After creating a role:

1. Assign the role to taxonomies to control knowledge access
2. Generate role-bound tokens for users with this role
3. Configure RBAC settings if not already enabled