Update Role

Update an existing role's properties. You can modify the name, description, and customer role ID of a role.

Endpoint

PUT /v1/workspaces/{workspaceId}/role/{roleId}

Authentication

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

Authorization: Bearer YOUR_ACCESS_TOKEN

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace
roleIdstring (UUID)YesThe UUID of the role to update

Request Body

All fields are optional. Only include fields you want to update.

FieldTypeRequiredDescription
namestringNoNew display name for the role
descriptionstringNoNew description for the role
customerRoleIdstringNoNew customer role identifier

Response

Success Response

Status Code: 200 OK

Headers:

X-API-Version: v1

Body:

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "role": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Senior Sales Manager",
    "description": "Updated description with broader access",
    "customerRoleId": "senior-sales-manager",
    "createdAt": "2025-11-11T10:00:00Z",
    "updatedAt": "2025-11-11T15:30:00Z"
  }
}
FieldTypeDescription
workflowIdstring (UUID)Workflow ID for tracking the async operation
roleobjectThe updated role object with all current properties

Examples

Update Name Only

curl -X PUT \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/123e4567-e89b-12d3-a456-426614174000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Senior Sales Manager"
  }'

Update Description

curl -X PUT \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/123e4567-e89b-12d3-a456-426614174000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Full access to sales content and analytics"
  }'

Update Multiple Fields

curl -X PUT \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/123e4567-e89b-12d3-a456-426614174000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Senior Sales Manager",
    "description": "Enhanced access to sales resources",
    "customerRoleId": "senior-sales-mgr"
  }'

Error Responses

400 Bad Request

Invalid request or field validation failed:

{
  "error": "Bad Request",
  "message": "Invalid field value"
}

401 Unauthorized

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

404 Not Found

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

409 Conflict

Customer role ID already exists:

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

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "Failed to update role"
}

Notes

Asynchronous Operation

Role updates are asynchronous. The API returns a workflowId.

Partial Updates

You can update one or more fields. Omitted fields remain unchanged.

Customer Role ID Uniqueness

If updating customerRoleId, the new value must be unique within the workspace.

Related Endpoints