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

This endpoint requires a Bearer token obtained through the two-step authentication flow:

First, generate an access token using your API key
Use that access token in the Authorization header

See Authentication for the complete authentication flow.

Required Headers:

Authorization: Bearer {access_token} - The JWT access token (NOT your raw API key)
organizationid: {your-organization-id} - Your organization ID

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:

# Step 1: Generate access token (do this once, reuse for multiple requests)
ACCESS_TOKEN=$(curl -s -X POST \
  'https://api.sharely.ai/workspaces/your-workspace-id/generate-access-key-token' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -d '{}' | jq -r '.token')
 
# Step 2: List roles using the access token
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id'

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:

# Using the access token from Step 1 above
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id'

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 API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const ORGANIZATION_ID = 'your-organization-id';
const API_BASE_URL = 'https://api.sharely.ai';
 
// Step 1: Generate access token
async function getAccessToken() {
  const response = await fetch(
    `${API_BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
      },
      body: JSON.stringify({})
    }
  );
  const data = await response.json();
  return data.token;
}
 
// Step 2: List roles
async function listRoles(accessToken) {
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID
      }
    }
  );
 
  const { roles } = await response.json();
  return roles;
}
 
// Usage
const accessToken = await getAccessToken();
const roles = await listRoles(accessToken);
// Use roles to populate a dropdown or list

Auditing Role Configuration

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

# Using the access token from the two-step authentication flow
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id' \
  | jq '.roles' > roles-backup.json

Checking Role Existence

Before creating a role, check if it already exists:

// Using the getAccessToken and listRoles functions from above
async function roleExists(accessToken, customerRoleId) {
  const roles = await listRoles(accessToken);
  return roles.some(role => role.customerRoleId === customerRoleId);
}
 
// Usage
const accessToken = await getAccessToken();
const exists = await roleExists(accessToken, 'sales-manager');