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 stableid, a displayname, and an optionaldescription(up to 2,000 characters) of what someone with the role may and may not do. Assignments reference roles byid, 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.
{ "version": "1.0", "roles": [] }. People get roles on the workspace’s
Members page, so nobody holds a new role until it is assigned there.
Built-in roles
Two roles exist on every workspace. They are virtual: they are applied automatically and never listed in theroles 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 oncontext.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.