Workspaces
What is a workspace?
Workspaces help users to organize, maintain, and store project data. Any Evo user can create workspaces within their organization.
Evo allows users to configure workspaces and to manage user roles and permissions.
The Workspaces API provides the space for the data to be stored, organized, and retrieved, but does not use or process the data. Whether a user with a certain role in a workspace will have access to perform an action on the data will depend on the Evo service's interpretation.
The workspace service hosts APIs which allow you to manage:
- Workspaces
- User roles within workspaces
- Workspace thumbnails
API operations
You can visit the Workspaces API OpenAPI schema for a detailed description of the endpoints.
Workspaces
You can create a workspace using a POST operation which responds with a workspace ID. You can use this workspace ID to manage the workspace in subsequent API requests. You can also retrieve a list of all workspaces that you have access to. Additional functionality is provided to you when retrieving multiple workspaces. For example, you can sort, filter, paginate, and limit the workspaces retrieved through various query parameters.
You can also update and delete a workspace. Updating a workspace can be done only if you have an owner or editor role in that workspace. In order to update, you must provide relevant metadata about the workspace. Deleting a workspace can be done only by the owner(s) of the workspace. By default, deleted workspaces will not be provided when retrieving workspaces through GET endpoints, however they can still be retrieved by appending a ?deleted=true parameter to the query string if desired.
User roles
User roles are designed to manage permissions within a workspace, i.e. assigning roles for a particular workspace. Users can be assigned one of three roles:
- Owner: This user can perform all actions in the workspace
- Editor: The user can perform all actions excluding hard-deleting of a workspace
- Viewer: The user can view the workspace
APIs enable you to manage the following:
- Assign a user a role in a workspace
- List user roles in a workspace
- Retrieve current user role
- Remove a user from a workspace
For detailed description of the roles' privileges, refer to this section
The creator of a workspace will have an "owner" role in the created workspace by default. They can add other owner(s) later, therefore the original creator can be removed by another owner. However, the created_by field in a workspace API response will always be set to the original creator's ID.
Workspace thumbnails
Users have the ability to upload, download, and delete thumbnails for their workspace. Supported formats are PNG, JPEG, and HEIC.
API permissions
The Workspaces API operations that can be carried out by the roles are:
| Action | Viewer | Editor | Owner |
|---|---|---|---|
| Create | * | * | * |
| Read | ✅ | ✅ | ✅ |
| Update | ❌ | ✅ | ✅ |
| Delete | ❌ | ❌ | ✅ |
Anyone can create a workspace, and they will have an "owner" role in the created workspace. Anyone can remove themselves from a workspace.
You may modify roles for a user up to and including the role that your account has. For example, if you are an "editor", you can add or remove the "viewer" or "editor" role on another user, but you cannot add or remove the "owner" role.
Administrative privileges
What role can administrators play within a workspace?
Evo admins are the users who have an administrator role in their organization. Evo admins have read access to all workspaces within their organization. They also have the ability to assign, modify, or delete users roles (owner, editor, or viewer) in the workspaces within their organization.
Exercising admin privileges
A separate set of endpoints with /admin in the path (e.g {domain}/workspace/admin/orgs/{org_id}/workspaces/) is provided for admins to interact with workspaces within the organization. This includes the GET endpoints for workspaces, user roles, thumbnails, and the POST/DELETE endpoints for user roles.
For a full description of available endpoints, see the Workspaces API OpenAPI schema.
What are the privileges of being an admin?
Admins have extra privilege by using /admin endpoints, allowing them to get and list workspaces in the organization that they may not have a role in already. Admins also have the ability to change user permissions for a workspace, e.g. adding a user, editing a user role, or deleting a user from a given workspace.
Admins do not have the ability to modify or delete any workspace they do not have an owner or editor role in.
General usage
Get started with the Workspaces API endpoints:
