Find Roles

Search for roles by specific criteria. This endpoint allows you to query roles by customer role ID or name.

Endpoint

POST /v1/workspaces/{workspaceId}/role/find

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.

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token with access token
`organizationid`	string (UUID)	Yes	Your organization ID
`Content-Type`	string	Yes	Must be `application/json`

Path Parameters

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

Request Body

At least one search criterion must be provided.

Field	Type	Required	Description
`customerRoleId`	string	No	Search by your custom role identifier
`name`	string	No	Search by role name (partial match supported)

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"
    }
  ],
  "total": 1
}

Field	Type	Description
`roles`	array	Array of matching role objects
`total`	number	Total number of matching roles

Examples

Find by Customer Role ID

Search for a role using your custom identifier:

# 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: Find role using the access token
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/find' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "sales-manager"
  }'

Response:

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sales Manager",
      "description": "Access to sales content",
      "customerRoleId": "sales-manager",
      "createdAt": "2025-11-11T10:00:00Z",
      "updatedAt": "2025-11-11T10:00:00Z"
    }
  ],
  "total": 1
}

Find by Name

Search for roles by name (supports partial matching):

# Using the access token from Step 1 above
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/find' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Manager"
  }'

Response:

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sales Manager",
      "description": "Access to sales content",
      "customerRoleId": "sales-manager",
      "createdAt": "2025-11-11T10:00:00Z",
      "updatedAt": "2025-11-11T10:00:00Z"
    },
    {
      "id": "987fcdeb-51a2-43f7-b8c9-123456789abc",
      "name": "Product Manager",
      "description": "Access to product information",
      "customerRoleId": "product-manager",
      "createdAt": "2025-11-10T14:00:00Z",
      "updatedAt": "2025-11-10T14:00:00Z"
    }
  ],
  "total": 2
}

Combine Search Criteria

Search using multiple criteria (results match ALL criteria):

# Using the access token from Step 1 above
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/find' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "sales-manager",
    "name": "Sales"
  }'

No Results

When no roles match the criteria:

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

Error Responses

400 Bad Request

No search criteria provided:

{
  "error": "Bad Request",
  "message": "At least one search criterion required"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

500 Internal Server Error

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

Notes

Search Behavior

Customer Role ID: Exact match only
Name: Partial match, case-insensitive
Multiple criteria: Results must match ALL provided criteria (AND logic)

Use Cases

This endpoint is useful when:

You know the customer role ID but need the Sharely UUID
You want to search for roles by name pattern
You need to verify if a role exists before creating it

Alternative Endpoints

For exact UUID lookup: Use Get Role
For exact customer role ID lookup: Use Get by Customer Role ID
For listing all roles: Use List Roles

Related Endpoints

List Roles - Get all roles
Get by Customer Role ID - Direct lookup by custom ID
Get Role - Get by UUID

Use Cases

Verify Role Exists

Check if a role exists before creating:

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: Check if role exists
async function roleExists(accessToken, customerRoleId) {
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role/find`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ customerRoleId })
    }
  );
 
  const { total } = await response.json();
  return total > 0;
}
 
// Usage
const accessToken = await getAccessToken();
const exists = await roleExists(accessToken, 'sales-manager');
console.log(`Role exists: ${exists}`);

Search and Display

Search for roles matching a pattern:

async function searchRoles(accessToken, searchTerm) {
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role/find`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: searchTerm })
    }
  );
 
  const { roles } = await response.json();
  return roles;
}
 
// Usage
const accessToken = await getAccessToken();
const matchingRoles = await searchRoles(accessToken, 'Manager');
console.log(`Found ${matchingRoles.length} matching roles`);