Managing Roles and Permissions in Crystallize

Authorization is a powerful security tool that can help you comply with laws and policies regarding the storage and access of sensitive data. With properly defined roles and permissions, you can ensure that your tenant's users are accessing only what is relevant to their particular function. This provides a better experience for them while also reducing the likelihood of errors.

Within each tenant, each user is assigned one role that defines what they're able to do and access. Tenant Admin is a built-in role that is automatically assigned to the first user who creates a tenant. When the tenant gains additional users, the Tenant Admin role can be assigned to them as well.

A Tenant Admin receives all permissions, and can:

• Read, create, update, and delete everything
• Access the Usage, Users, Roles, Billing & Payments, and API Access screens in the Crystallize App
• Invite users to the tenant
• Create custom roles
• Assign roles to other users
• Copy tenants
• Read signature secrets

The Tenant Admin role cannot be deleted, and its permissions can't be changed.

When additional users are invited to a tenant, they can be assigned a Tenant Admin or custom role within that tenant (more on custom roles below). Users who are invited to a tenant without being assigned a role will be given a default "user" role that they will have until someone with the appropriate permissions assigns them a new role.

There will likely be situations where you want to refine what a user can access. For instance, you may want your content editors to have full access to the catalogue, but not be able to view or modify orders. In such cases, you can create a custom role that specifies exactly what this particular user will be able to see and do.

A user with the appropriate permissions can define custom roles within the Crystallize App or by using the Core API. Below, we'll show you how to do it within the App.

A user with the appropriate permissions can go to the Settings screen and click the Roles label to reach the Roles screen.

Click the plus sign button (+) in the top left panel to create a new role. Type in a name for the role, then click the Create button.

Add permissions to the role by clicking the different buttons in the skill tree beneath. The larger buttons (Tree, Orders, etc.) grant access to read permissions. You can individually click on Create, Update, Delete, etc. buttons to add those permissions as well. Most of these permissions apply both to the Crystallize App as well as API access.

Some permissions may have dependencies that you'll also need to enable. For instance, a role that has read permissions for the Tree (catalogue) must also be given read permissions for Shapes, Languages, Price Variants, Tax Groups, Stock Locations, and Subscription Plans.

Permissions can be assigned for the following: 

Catalogue

• Tree (catalogue/item access, along with tree operations such as browsing and reorganizing)
• Topics
• Grids
• Assets
• Flows

Commerce

• Orders
• Customers
• Pipelines
• Reports

Build

• Shapes
• Webhooks
• Price variants
• Tax groups
• Subscription plans
• Subscription contracts
• Languages
• Stock locations
• Apps

Manage

• Users
• Roles

In the Role Details section on the right side of the screen, you'll see the avatar for the role currently being viewed. Under Role Overview is a summary of the permissions and dependencies the role will have. Click the names of each permission category to access checkboxes for the different options, and to access the Give full access button to enable all permissions at once.

For some permission categories, it’s possible to set additional user interface (UI) settings. These settings apply only to the Crystallize App, and do not affect API access. They're not permissions, and shouldn't be used as such. But they can be used, for instance, to limit a Regional Manager role to only seeing/modifying prices in their local currency.

To access UI settings, click on the permission category name under Role Overview, then click on the UI preferences tab.

• Pipelines: The Hide fulfilment pipeline settings from navigation checkbox can be used to hide the Fulfilment menu from users with this role. You can also control the visibility, editability, and ordering of pipelines for users with this role.
• Price variants: You can toggle the visibility and editability of each price variant defined within your tenant. 
• Shapes: The Hide shapes settings from navigation checkbox can be used to hide the Shapes menu from users with this role. You can also control the visibility and ordering of shapes that users with this role will see when they create new items for the catalogue. By clicking on any shape name, you can further define the visibility, ordering, and editability of the shape's components and pieces.  Use the Product and Variant tabs to access the components defined at the product and product variant level. At the product variant level, you can also control the editability and/or visibility of names, attributes, SKUs, and the Media component.

The Tree permission allows you to further define conditional access. For instance, you may want to limit a user to only working with certain items in the catalogue, in certain languages. To do this, click on the word Tree under Role Overview. In the Conditional Access section, click the Add Condition button. You can then click the plus sign button (+) beside Languages to pick the languages this role will have access to. You can click the plus sign button (+) beside Catalogue to browse for catalogue items that a user may access, and add them by clicking and dragging them from the left-hand browsing panel onto the Catalogue pane. Click the X on an item or language label to remove it from the condition. Once finished, click the Create condition button.

Once conditions have been added, you can use the action button (...) beside each one to edit or remove them. 

A mushroom icon will appear on the Tree icon to indicate that one or more conditions have been defined.

Once you’ve configured a role as desired, click the Update button in the top right area of the screen to save your changes. The users assigned to a modified role should see changes take effect immediately on their end. Otherwise, they may have to refresh their browser windows.

A role can only be deleted if it's not assigned to any users. To delete a role, select it from the left-hand panel, then click the action button (…) in the top right and choose Delete. Deletion cannot be undone, so proceed carefully.

A user with the appropriate permissions can browse to the Settings screen and click the Users label to see all users who have access to the tenant, along with their currently assigned roles. Use the drop-down menu under the Role column to assign one of the available roles to each user. (Note that Tenant Admins cannot be assigned a different role.)

When a user's permissions change, they should see the change take effect immediately. Otherwise, they may have to refresh their browser window.