Spaces & subspaces

Spaces and subspaces are the top-level and second-level way that projects are organized in the Instabase file system.

Settings for Spaces & Subspaces are accessible at Admin > Spaces & Subspaces. You must have site admin privileges to adjust most space settings.

Spaces

Spaces are the top-level way to group data. Spaces contain subspaces and have managers.

There are two types of Spaces:

  • User Spaces: If user spaces are enabled, each user has their own space named after their username. The only manager of a user space is the user.

  • Organization Spaces: These spaces can have multiple Managers and host shared data.

To see the contents of a Space, navigate to Explorer and select the Space from the Space selector in the top left.

Space permissions

User Spaces always have exactly one Space Manager, and Organization Spaces can have any number of Space Managers.

Space Manager powers include:

  • Creating Subspaces in the Space

  • Automatically being a subspace manager of each subspace

  • For Organization Spaces (not applicable for User Spaces):

    • Deleting the Space

    • Adding/removing other Space Managers

    • Editing the display name and description

Site Admins have Space Manager permission for all Spaces, including User Spaces. Users with the Manage Organization Spaces permission have Space Manager permissions only for Organization Spaces.

Viewing spaces

To manage your Spaces, or to access the Subspaces you can manage, navigate to the Admin app then to Spaces & subspaces.

Site Admins will see two tabs:

My spaces & subspaces allows you to see the Spaces to which you’ve either been:

  • Explicitly given access to as Space Managers

  • Given access to Subspaces within the Space explicitly as a Subspace Manager. In this view, you can see how many Subspaces within the Space you are a Subspace Manager of, and how many you can access but are not a Subspace Manager of. You can also see a list of the Space Managers. Up to three are shown at a time; you can select See more to see the entire list in a modal.

All spaces allows you to search for any User Space, and displays a list of all Organization Spaces.

Users with the Manage Organization Spaces permission will also see two tabs, but will be unable to search for User Spaces in All Spaces.

All other users will not see any tabs, and will see the My spaces & subspaces view by default.

Creating new spaces

Site Admins and Users with the Manage Organization Spaces permission can create Organization Spaces. To create an Organization Space, go to Spaces & subspaces in Admin and click Create Organization.

This will open a dialog:

  • Internal name: The unique identifier for the Space without whitespace characters that will be used in the URL (this cannot be changed, and must be unique among both Organization and User Spaces).

  • Display name: A “user-friendly” title for your Space; it does not have to be unique.

  • Description: A description of your Space.

  • Add me as a space manager: Whether you should be added as the first Space Manager; if this is not selected, you will have to go to the All spaces tab to find the Space, rather than the My spaces & subspaces tab

Managing a space

To navigate to a Space, click on the Space in the Spaces & subspaces view of Admin.

From here you will be able to navigate to any Subspaces you are a Subspace Manager of. Subspaces for which you have a collaborator or custom role are visible but disabled.

If you are a Space Manager, you can also take other actions:

  • Create new Subspaces within the Organization by selecting Create new Subspace and inputting an name unique within the Space, a description, and choosing whether the Subspace should be Private or Public.

  • For Organization Spaces (not applicable for User Spaces):

    • Delete the Space by selecting Edit next to the Space name and selecting Delete in the dropdown

    • Edit the Space by selecting Edit next to the Space name and selecting Edit in the dropdown; from here you can change the display name and description and save your changes

    • Add or remove Space Managers by selecting Manage in the Managers section; you can add both Users and Groups as Space Managers

Subspaces

Subspaces are the unit of data hierarchy under spaces. Spaces can have multiple subspaces. Within subspaces, drives and databases can be mounted to access your data. For more information on mounts, see mounting databases and mounting drives.

To see the contents of a Subspace, navigate to Explorer, select the Space to which the Subspace belongs from the Space selector in the top left, then select the Subspace from the list below.

Subspace permissions

There are three possible roles for users given access to a Subspace:

  • Managers can:

    • Delete the Subspace

    • Edit the Subspace name and description

    • Change, remove, or add roles for other Users and Groups

    • Read/write/delete all data in the Subspace

    • Use the data in all apps

  • Collaborators can:

    • Read/write/delete all data in the Subspace

    • Use the data in all apps

  • Custom roles can:

    • Only read/write/delete data that they have specifically been given permission to

    • Only use that data in apps they have specifically been given permission to

All space managers for the parent space are automatically subspace managers. Site admins also have subspace manager permissions for all subspaces, and users with the Manage Organization Spaces permission have subspace manager permissions for subspaces that belong to organization spaces, but not user spaces.

Viewing a subspace

There are two ways to navigate to the page to manage a Subspace:

  • Navigate to the Subspace via Explorer, hover your mouse over the Subspace name, and select the gear icon.

  • Navigate to Spaces & subspaces in the Admin app, select the parent Space (if you are not a Subspace Manager but are instead a Site Admin or can Manage Organization Spaces, you can reach it via the All spaces tab), and select the Subspace from the list of Subspaces. Alternatively, use the dropdowns at the top of the page to navigate between Subspaces and Spaces.

Managing a subspace

As a Subspace Manager, you can edit the Subspace itself:

  • Delete the Subspace by selecting Edit next to the Subspace name and selecting Delete in the dropdown.

    • When deleting a subspace, users can permanently purge all files on the default Instabase Drive. Select “Also delete all files stored on the attached Instabase Drive” from the delete dialog to purge the files. This will permanently delete all files from the Instabase Drive, so use this option carefully.

  • Edit the Subspace by selecting Edit next to the Subspace name and selecting Edit in the dropdown; from here you can change:

    • The name - this must be unique in the Space. Changing the name will cause all links to the Subspace to break, as the URL will change.

    • The description

    • The visibility - private subspaces can be viewed only by users given permission to do so. The contents of public can be viewed by anyone, including guests without Instabase accounts, but can be edited only by Users with given permission to do so.

    • The owner - the parent Space can be changed to any Space of which you are a Space Manager.

Subspace Managers can also edit other Users’ and Groups’ permissions.

The Groups tab shows all the groups who have any role in the Subspace and why they have that role. If the Group is a Space Manager of the parent Space, the group will automatically show up and changing the role will be disabled, with Space Manager showing in the Role derived from column; in order to change it, they must first be removed as a Space Manager. Otherwise, Groups can:

  • Be added by selecting Add Groups then selecting in each category of Managers, Collaborators, and Custom the Groups you’d like to add

  • Have their role changed through the Role dropdown

  • Be marked for deletion by selecting the X at the end of the row

Before navigating away from the tab or page, changes must be saved.

The Users tab shows all the Users who have any role in the Subspace and why they have that role. If they are a Subspace Manager because they are a Space Manager or a member of a Group that is a Space Manager, editing that User’s permissions will be disabled, with Space Manager showing in the Role derived from column; in order to change it, they must first be removed as a Space Manager.

If a Group is added to the Subspace of which the User is a member, it will be listed in the Member of groups column. A User will inherit the permissions of all the Groups they are a member of; for example:

  • If they are in both a Manager Group and Collaborator Group, they will be a Manager because it is the higher of the two

  • If they are in a two Groups with Custom roles, they will have the union of all those custom permissions

  • If they are in a Collaborator Group, they could not individually be given a Custom role, but they could be given a Manager role; the other Users in the Group would remain Collaborators, but this User would be a Manager in their own right and thus not have their role derived from any Group, despite being part of the Group

A User cannot have their role downgraded to lower than what they inherit from a Group they belong to; they must first be removed frm the Group or the Group must be removed from the Subspace.

In this view, Users can:

  • Be added by selecting Add Users then deleting in each category of Managers, Collaborators, and Custom the Users you’d like to add

  • Have their role changed through the Role dropdown (if their role isn’t derived from being a Space Manager or a Group, or the Group has only a Collaborator or Custom role)

  • Be marked for deletion by selecting the X at the end of the row (if their role isn’t derived from being a Space Manager or a Group)

Purging subspace data

You can purge all data stored on the Instabase drive when deleting a subspace. Purging the data permanently deletes all stored files and file versions, as required by SOC2 and GDPR requirements for customer data deletion.

The Instabase drive contains data that is stored in AWS S3 and managed by Instabase itself. Instabase can purge only its own drive—you have control of any externally-mounted drives and can purge that data yourself.

After you purge the data, you can verify the purge results in Instabase logs or by checking the AWS S3 bucket. If you want to verify the purge by checking the S3 bucket, be sure to note the S3 mount details from the Instabase drive before deleting the subspace. You can find the Instabase drive in the Explorer.

Important: This procedure permanently deletes the customer data stored on the Instabase drive. Unlike a normal subspace deletion, you cannot recover this data.

  1. Open Explorer.

  2. From the dropdown menu, select the user space containing the subspace you want to purge.

  3. Hover over the subspace, and then click on the gear icon.

  4. Under Space & Subspace Management, click Edit.

  5. Click Delete.

  6. When confirming the deletion, check Also delete all files stored on the attached Instabase Drive.

  7. Click Delete to confirm the deletion and purge.

After you confirm deletion, it might take some time for Instabase to complete the purge from S3, depending on the size of the drive. To confirm deletion, you can:

  • Check the grpc-file-service logs to confirm that the purge finished.

  • Log in to the Instabase S3 bucket, find the prefix for the deleted Instabase drive, and confirm that the data was truly deleted. To do this, you need the S3 mount details from before you deleted the subspace.

Custom roles

After adding a User or Group with a Custom role, you must assign that entity granular permissions before saving. Selecting the circular arrow button next to the Save button will open up the Custom role view, as will setting any entity’s role to Custom.

Custom permissions can be set for both Applications and Drives.

In the Applications tab, you can set permissions for apps for the Users or Groups who have Custom roles. For most Instabase apps, some subset of the following permissions can be given; see the documentation for each app, because their effects can vary app-to-app:

  • Web Read: Open files in the app in the UI

  • Web Write: Save files edited by the app in the UI

  • Web Execute: Save files edited by the app in the UI

  • API Read: Open files in the app via API

  • API Write: Save files edited by the app via API

  • API Execute: Execute operation in the app via API

In the Drives tab, you can set permissions for individual drives for the Users or Groups who have Custom roles. First, select a drive from the dropdown (one will be automatically selected). Then, choose the path prefix for which you wish to assign permissions or add a new path prefix by selecting the + button. A permission on the / path would mean that an entity would be given permissions for the entire drive. More specific paths (for example, /files) would give the user permissions only for the paths that start with that string. For each path prefix, the following permissions can be given:

  • FS Read: View the contents of a file or folder and download them

  • FS Write: Edit the contents of a file or folder

  • FS Delete: Delete a file or folder (including through renaming or moving)