Roles

Roles let space owners and admins control users' access to resources within a specific space. A role is a set of permissions associated with one or more users.

Each space includes default roles with predefined permissions that cannot be modified:

Role	Permissions
Admin	Manage users, content, apps, and any other aspect of the space
Editor	Create, update, and delete content
Owner	The space creator has all admin-level permissions in addition to roles' management

Space owners and admins can also create custom roles to match the project's content requirements and the organization's editorial team. Use custom roles to apply granular permissions and assign them to individual users.

Note

The number of roles and users depends on the current plan. Learn more about Storyblok Pricing.

To create new custom roles or manage existing ones, open Settings → Roles. Choose an existing custom role to update its permissions, or select + Add new role to create a new role with relevant options and permissions.

Note

To configure SSO integration, select This role is for integration with SSO and provide the necessary information.

The benefits of custom roles

Custom roles are an efficient way to define which users can perform specific actions.

For example, an admin of a multilingual project can assign a German translator role to users who need full access to German content and read-only access to English content.

Note

To learn how to use roles with workflows and releases, visit the roles manual.

Different types of users—such as developers and designers—may have their own roles, granting them access to edit blocks and upload assets, respectively.

To assign roles to users, open Settings → Users and select the relevant person. Then, choose Single role or Multiple roles and select the appropriate roles from the dropdown.

Conflicting permissions for multi-role users

A user can have multiple roles in a single space and different roles in other spaces. This has a notable consequence.

If a user is assigned to multiple roles, where one role can access specific resources and another can't, the role without access takes priority. For example, User 1 is assigned to both Role A and Role B. Role A is allowed to access Story 1, but Role B is denied access to Story 1. In this case, User 1 can't access Story 1.

When two roles have conflicting permissions, the deny status prevails

Permissions

Permissions determine which resources and actions a role (and therefore users assigned to it) can access.

Storyblok supports an extensive list of permission levels, allowing admins to manage access to stories, blocks, fields, assets, languages, datasources, tags, and apps.

To view or set permissions, open Settings → Roles, and select the role. Each tab covers different permissions configurations:

Tab	Description
General	• Allow or deny various actions in stories, folders, and pipelines. • Allow or deny access to the Image editor, Visual editor, and stories' JSON payload. • Hide all stories or folders. To allow users to read content, select the Allow reading content option. • Allow or deny managing tags. • Allow or deny editing datasources' values and keys. • Allow or deny access to an e-commerce app (if installed). • Allow or deny performing actions in the Task Manager app (if installed).
Content	Manage access to selected languages, pipelines, folders, and stories using an allowlist/denylist. To allow users to read content, open General and select the Allow reading content option.
Blocks	• Grant access to the block library. • Manage access to selected blocks and block folders using an allowlist/denylist. • Manage access to selected block fields using an allowlist/denylist.
Datasources	Manage access to selected datasources using an allowlist/denylist.
Assets	Manage access to selected asset folders using an allowlist/denylist.

In most cases, the default state is “allowed”: the role can access any resource that isn't explicitly restricted.

Tip

Use the space roles endpoint to add, delete, or update custom roles and permissions programmatically.

For a complete list of permissions and default states, check the Space Role Object reference in the Management API documentation.

Folders, sub-folders, and individual resources

Storyblok supports organizing stories and blocks in folders. The permissions settings use a separate allowlist/denylist for individual stories or blocks and the folders that contain them.

Applying granular permissions to individual blocks and folders is a powerful way to limit access to restricted resources. Sometimes, you may want to automatically extend these permissions to all resources stored under the same parent folder. To do that, select Blocks → Apply permissions to sub-items.

Allowlist or denylist

Most permissions settings support allowlists and denylists that enable admins to create complex permission schemes:

• Use a denylist to limit access to specific resources. Everything else is accessible.
• Use an allowlist to grant access only to specific resources. To ensure a tight lockdown, pair this with the Hide content if unauthorized and Hide folders if unauthorized options in the General tab.

Tip

To avoid having to add each new resource to an allowlist, create a parent folder, add it to the list of allowed items, and place all relevant resources and sub-folders inside it.

The difference can seem subtle, so the approach you adopt depends on the nature and sensitivity levels of your content, as well as your team's organizational structure.