Delete Role

Delete a role from your workspace. This is an asynchronous operation that removes the role and all its associations.

Endpoint

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

Response

Success Response

Status Code: 200 OK

Headers:

X-API-Version: v1

Body:

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Role deletion initiated"
}

Examples

Delete a Role

curl -X DELETE \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: sk-sharely-your-api-key'

Response:

{
  "workflowId": "789e0123-f45a-67b8-c901-234567890def",
  "message": "Role deletion initiated"
}

Error Responses

401 Unauthorized

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

404 Not Found

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

409 Conflict

Role is still in use:

{
  "error": "Conflict",
  "message": "Cannot delete role: still assigned to taxonomies or users"
}

500 Internal Server Error

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

Notes

Asynchronous Processing

Role deletion is asynchronous. The API returns immediately with a workflowId.

Cascade Effects

Deleting a role:

• Removes it from all taxonomies
• Invalidates role-bound tokens
• May affect user access to knowledge

Cannot Be Undone

Role deletion is permanent and cannot be reversed. Ensure you want to delete the role before proceeding.

Check Dependencies First

Before deleting a role, verify it's not actively used:

1. Check taxonomy assignments
2. Review active role-bound tokens
3. Audit user access dependencies

Best Practices

Soft Delete Alternative

Consider deactivating or renaming roles instead of deleting them to maintain audit trails.

Communication

Notify stakeholders before deleting roles that affect user access.

Backup

Export role configuration before deletion for record-keeping.

Related Endpoints

• List Roles - View all roles before deletion
• Get Role - Verify role details before deleting