Skip to main content
A workspace’s roles live in a zite.permissions.json file at the workspace root. This is the schema reference; for the concepts, see Roles & permissions.

Structure

Fields

  • version: always "1.0".
  • roles: your custom roles, each with a stable id, a display name, and an optional description (up to 2,000 characters) of what someone with the role may and may not do. Assignments reference roles by id, so renaming a role never breaks a member’s assignment. Role names must be unique, ignoring case. Do not list the built-in roles here (see below).
  • builtinRoles: optional descriptions for the built-in roles, keyed by built-in id. Their names can’t be changed.
A new workspace starts with { "version": "1.0", "roles": [] }. People get roles on the workspace’s Members page, so nobody holds a new role until it is assigned there.
The file defines roles. It does not enforce anything. There are no table rules or row filters, and the platform does not check roles on database access. A role’s limits hold only where a workflow checks for it.

Built-in roles

Two roles exist on every workspace. They are virtual: they are applied automatically and never listed in the roles array. An entry carrying a built-in id and its exact name is stripped when the file is read, and a built-in id under any other name is rejected. A signed-out visitor on a workflow without authenticated: true has no context.user, so holds no roles at all, builtin:all-users included. To require a session, set authenticated: true on the workflow rather than checking for builtin:all-users.

Checking roles in a workflow

The caller’s roles are on context.user.roles as { id, name }[]. Check them with hasRole from zitejs/backend, matching on the role’s id, never its name:
useAuth() does not carry roles. If the frontend needs them to hide actions, return them from a workflow. Hiding a button is a courtesy, not a control: the workflow check is what enforces the rule.

Example