List Roles

Retrieve all roles in your workspace. This endpoint returns a list of all roles that have been created for RBAC control.

Endpoint

GET /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

Parameter	Type	Required	Description
`workspaceId`	string (UUID)	Yes	The ID of your workspace

Response

Success Response

Status Code: 200 OK

Headers:

X-API-Version: v1

Body:

{
  "roles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Sales Manager",
      "description": "Access to sales-related content",
      "customerRoleId": "sales-manager",
      "createdAt": "2025-11-11T10:00:00Z",
      "updatedAt": "2025-11-11T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Content Editor",
      "description": "Can edit and manage content",
      "customerRoleId": "content-editor",
      "createdAt": "2025-11-10T15:30:00Z",
      "updatedAt": "2025-11-10T15:30:00Z"
    }
  ],
  "total": 2
}

Field	Type	Description
`roles`	array	Array of role objects
`roles[].id`	string (UUID)	Sharely's unique identifier for the role
`roles[].name`	string	Display name of the role
`roles[].description`	string	Optional description of the role's purpose
`roles[].customerRoleId`	string	Your custom identifier for the role
`roles[].createdAt`	string (ISO 8601)	When the role was created
`roles[].updatedAt`	string (ISO 8601)	When the role was last updated
`total`	number	Total number of roles in the workspace

Examples

Basic Request

List all roles in your workspace:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'x-api-key: sk-sharely-your-api-key'

Response:

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Administrator",
      "description": "Full access to all resources",
      "customerRoleId": "admin",
      "createdAt": "2025-11-01T08:00:00Z",
      "updatedAt": "2025-11-01T08:00:00Z"
    },
    {
      "id": "987fcdeb-51a2-43f7-b8c9-123456789abc",
      "name": "Viewer",
      "description": "Read-only access",
      "customerRoleId": "viewer",
      "createdAt": "2025-11-02T09:15:00Z",
      "updatedAt": "2025-11-02T09:15:00Z"
    }
  ],
  "total": 2
}

Empty Workspace

Response when no roles exist:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'x-api-key: sk-sharely-your-api-key'

Response:

{
  "roles": [],
  "total": 0
}

Error Responses

401 Unauthorized

Invalid or missing API key:

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

403 Forbidden

Insufficient permissions for the workspace:

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

404 Not Found

Workspace not found:

{
  "error": "Not Found",
  "message": "Workspace not found"
}

500 Internal Server Error

Server error during processing:

{
  "error": "Internal Server Error",
  "message": "Failed to retrieve roles"
}

Notes

Response Ordering

Roles are typically returned in the order they were created, with the most recently created roles appearing last. However, you should not rely on this ordering in your application logic.

Pagination

Currently, this endpoint returns all roles in a single response. For workspaces with a large number of roles, pagination may be added in future API versions.

Role Permissions

The roles returned by this endpoint represent the complete set of roles configured for your workspace. To see which taxonomies or knowledge items are associated with each role, use the Taxonomies API.

RBAC Status

This endpoint will return roles even if RBAC is disabled for the workspace. However, the roles will not be enforced until RBAC is enabled.

Related Endpoints

Create Role - Create a new role
Get Role - Get a specific role by UUID
Find Roles - Search for roles by criteria
Get by Customer Role ID - Get role by your custom identifier

Use Cases

Listing Available Roles

Display all available roles in your application's role selection UI:

const response = await fetch(
  `https://api.sharely.ai/v1/workspaces/${workspaceId}/role`,
  {
    headers: {
      'x-api-key': 'sk-sharely-your-api-key'
    }
  }
);
 
const { roles } = await response.json();
// Use roles to populate a dropdown or list

Auditing Role Configuration

Retrieve and audit all configured roles for compliance or documentation purposes:

# Export all roles to a file
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  | jq '.roles' > roles-backup.json

Checking Role Existence

Before creating a role, check if it already exists:

async function roleExists(workspaceId, customerRoleId) {
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role`,
    {
      headers: { 'x-api-key': 'sk-sharely-your-api-key' }
    }
  );
 
  const { roles } = await response.json();
  return roles.some(role => role.customerRoleId === customerRoleId);
}