Object permissions

Object permissions limit which objects of a type a specific user or user group can see. Each permission is a StarQL condition on the type: the user or group sees only the objects that match it, everywhere in Starhive. Space access decides who can enter a space at all, and attribute permissions decide which attribute values they can see; object permissions sit between the two and decide which objects they see.

A typical use: a Hardware type shared by several teams, where each support group should only see the devices at its own site, or a Contracts type where account managers only see the contracts they own.

Object permissions are available on the Essential plan and higher. If a workspace moves to a plan without them, existing permissions keep applying and can still be deleted, but no new ones can be added or edited until the workspace is back on a plan that includes them.

How a permission works

A permission belongs to one type and applies to one subject: a single user or a user group. Each user or group can have at most one permission per type.
The condition is StarQL written against the type's attributes, the same way you would filter the type's objects, without an order by clause. It can follow references with dot notation, including references to objects in spaces the user can't open themselves.
Someone with a permission on a type sees an object of that type only if it matches their condition. If several permissions apply to them on the same type, their own and those of every group they belong to, they see an object when it matches any of them.
A type with no permission for a given user is not restricted for them: they see every object their space access allows, as before.
A permission on a type also applies to every type that extends it, alongside any permissions set on the subtype itself.
Workspace owners and admins are never restricted. Object permissions apply to members, and to external users.

caution

Conditions refer to attributes by name. If you rename an attribute that a condition uses, the condition can no longer be evaluated and grants nothing, so its user or group sees no objects of that type until you update the condition. Deleting such an attribute deletes the permission with it (you are warned first, see Deleting an attribute used in a permission).

Where permissions apply

Permissions apply everywhere objects are read, not only in the space's views: search and global search, object counts, sites and their widgets, CSV exports, imports, the API, Nova, and notifications. Someone whose permission hides an object:

doesn't see it in any list, view, search result, widget or export, and can't open it by link;
can't edit, delete, clone, comment on or watch it, and isn't notified about it even as a watcher;
sees a reference to it on another object as Restricted rather than the object's name. They can't add a reference to a hidden object, and a hidden reference an object already holds is kept when they edit that attribute;
doesn't see its history.

What a restricted user sees

Wherever a permission may be hiding objects, Starhive says so, so a short list or a low count isn't mistaken for missing data:

In a type's views, a Permission-filtered lock pill sits next to the object count. Its tooltip reads "Your object permissions may hide some objects here. Counts only include objects you can see."
Under an Object list widget on a site, a Filtered by your object permissions line appears.
After creating, editing or cloning an object whose new values fall outside their permission, the user is warned: "Saved. This object no longer matches your object permissions, so it will be filtered out and you won't be able to see it." The save itself goes through.
Before a CSV import into a type their permission covers, the import dialog warns that some imported objects may be hidden from them. Once the import completes, its Activity log entry says how many of the imported objects are visible to them.

Managing permissions

Only space admins and owners can view, add, edit or delete a type's object permissions.

Open space configuration, then in the Types tree open the type's ⋮ menu and choose Object permissions.

The dialog lists the type's permission rules, each with the user or group it applies to and its condition. A type that has permissions, or inherits them from a type it extends, shows a lock next to its name in its configuration panel; the lock's tooltip names the type the permissions come from.

Adding a permission

Click Add permission, choose whether the permission applies to a User group or a User, pick the group or user, and enter the StarQL condition. The condition field offers the type's attributes as you type and is validated against the type when you save.

Only people who can see the type's space are offered. In an open space, or a closed space with a default access level, that is everyone in the workspace; in a closed space without a default level it is the users and groups granted the space. If the workspace has no user groups yet, the dialog links to Settings → Groups so you can create one, or you can pick a single user instead.

Editing and deleting a permission

From a rule's ⋯ menu, Edit changes its condition; the user or group it applies to can't be changed, so to move a permission to someone else, delete it and add a new one. Delete asks for confirmation inline and removes the rule, after which the user or group sees every object of the type again, subject to any other permissions that apply to them.

A group's permissions can also be reached from the group itself: the Permissions tab of a user group lists its object permissions by space and type, with their conditions. From there, Edit condition and Remove access are available for the types in spaces where you are a space admin or owner.

Deleting an attribute used in a permission

When you delete an attribute that one or more conditions filter on, the delete dialog lists those permissions and the types they are on, and warns that deleting the attribute also deletes them. Once deleted, those users and groups are no longer limited on that type.

Permissions are also removed automatically when their type or space is deleted, when their user is removed from the workspace, or when their user group is deleted.

Audit log

Every permission added, edited or deleted is recorded in the workspace audit log as OBJECT_PERMISSION_CREATED, OBJECT_PERMISSION_UPDATED or OBJECT_PERMISSION_DELETED. The entry is recorded against the type, so searching the log for a type finds every change to who can see its objects.

How a permission works​

Where permissions apply​

What a restricted user sees​

Managing permissions​

Adding a permission​

Editing and deleting a permission​

Deleting an attribute used in a permission​

Audit log​