Management API permissions

#Overview

The same set of Management API permissions is available for both Roles and Permanent Auth Tokens. Some permissions are view permissions, meaning they have an impact on what a user assigned to a role can see in the UI, while other permissions will allow certain actions through the Management API when granted.

Default permissions for both are different. Default role permissions ensure that users can access the UI - mostly read permissions - and for PATs, the defaults cover certain create and read permissions.

Anything beyond the defaults, you can manually add depending on what you need.

If you lack the necessary permissions:

Roles: You will not be able to see parts of the UI - such as a button - you will get an error trying to access parts of the UI, or will be logged out.
Tokens: You will get an error message indicating you don't have the necessary permissions.

#Roles

Custom roles are an enterprise feature. Contact our sales team to access it.

Some Management API permissions affect how you can interact with the UI.

The default Management API permissions that you get for a custom role are the basics that you need to view the UI correctly.

All default permissions are UI-related and ensure you can use the webapp. On top of that, you can grant other permissions, depending on what you want the role to be able to do.

Hygraph offers system roles for Admin, Editor, Developer, and Contributor. The permissions configured OOB for these roles show role-based differences that reflect the tasks each should be able to perform in the system. This is why a user under the role of Editor won't be able to see the API Playground in the UI, while a user under the role of Admin or Developer can.

It is possible to grant a role all content permissions and still use the Management API permissions to hide buttons in the UI for all users assigned to that role. However, bear in mind that in this case, if a user has access to the API, they will still be able to take those actions since they have the content permissions granted; it's just that in the UI, they won't be able to because certain buttons and actions are hidden to them.

#Default role permissions

These are the permissions that a user needs to have to view the UI correctly.

PERMISSION	DESCRIPTION
Read existing fields	If this permission is not granted, the user cannot see or access the `Fields` tab in the UI.
Read existing enumerations	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but they won't be able to see the enumerations in it.
Read locales	If this permission is not granted, users will get an error when trying to access the app.
Read public view groups	If this permission is not granted, users will get an error when trying to access the content editor.
Read existing components	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but they won't be able to see the components in it.
Read existing entries	If this permission is not granted, users won't be able to see or access the `Content` and `Assets` tabs in the app.
Read public content views	If this permission is not granted, users will get an error when trying to access the content editor.
Read existing environments	If this permission is not granted, users cannot access the project and will get an error attempting to log in.
Read remote sources	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but they won't be able to see the remote sources in it.
Read stages	If this permission is not granted, users will get an error when trying to access the app.
Read existing models	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but they won't be able to see the models in it.

#Additional role permissions

PERMISSION	DESCRIPTION
Assign a role to a user	If this permission is not granted, the user cannot see the `Assign role` option in `Project Settings > Team > Members`.
Can add app installations	If this permission is not granted, the `Explore apps` banner is hidden in the Apps section of the UI. Projects where this permission is not granted to the user do not display on the project selector dropdown for new app installations.
Can create content permissions	If this permission is not granted, users cannot see the Add permission option in the Public Content API, roles, and PATs sections of the project settings.
Can create new permanent auth tokens	This permission allows users to create new permanent auth tokens. If this permission is not granted, users can't see the `+ Add Token` button at the top of the Permanent Auth Tokens screen in Project Settings.
Can delete app installations	If this permission is not granted, the user cannot see the `Uninstall` app option in the app cards context menu.
Can delete content permissions	If this permission is not granted, users cannot see the Delete option for content permissions in the Public Content API, roles, and PATs sections of the project settings.
Can delete existing permanent auth tokens	This permission allows users to delete permanent auth tokens. If this permission is not granted, users can't see the `Delete` option inside the context menu of permanent auto tokens in the `Access` section of Project Settings.
Can read content permissions	If this permission is not granted, the user cannot see the `Content permissions` block for roles and PATs.
Can read existing permanent auth tokens	This permission allows users to see the Access section in Project Settings. If you want to give someone access to the API Playground, this permission needs to be granted, along with `Can see API Playground`, because on the Playground, we load Auth Tokens to show them on the dropdown.
Can see Role & Permissions Settings	If this permission is not granted, the user cannot see the `Roles` menu in the project settings.
Can see schema view	View permission that allows a user to see the Schema builder. You can choose to deselect this permission to hide the schema view for roles for which it's not relevant.
Can see Team Member Settings	If this permission is not granted, the user cannot see the `Members` tab in `Project Settings > Team`.
Can update app installations	This permission grants the user the ability to see the `Edit` button on app cards.
Can update content permissions	If this permission is not granted, users cannot see the `Edit` option for content permissions in the Public Content API, roles, and PATs sections of the project settings.
Can update existing permanent auth tokens	This permission allows users to edit permanent auth tokens. If this permission is not granted, users can't see the `Edit` option inside the context menu of permanent auto tokens in the `Access` section of Project Settings.
Can use the playground	If this permission is not granted, the users cannot see the API Playground in the top-level menu, and the `Preview in playground` option in the Content editor and Assets.
Change the name, picture and description of a project	This permission allows users to edit the project details in `Project Settings > General > Project`. The whole section will be visible but grayed out and read-only if this permission is not granted.
Create a new environment backup	This permission allows creating a new environment backup.
Create locales	This permission allows users to create new locales in a project. If this permission is not granted, users cannot use the `Add` button at the top of the existing locales in `Project Settings > General > Locales`.
Create new components	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but will not be able to use the `+ Add` button to create new components.
Create new entries	This permission grants you the ability to create new entries. If you do not select it, the user will not see the `+ Add entry` button at the top right corner of the content editor screen.
Create new enumerations	If this permission is not granted to a user who has the `Can see schema` view permission, they will be able to access the Schema builder, but will not be able to use the `+ Add` button to create new enumerations.
Create new environment	If this permission is not granted, the `Clone` button in `Project Settings > General > Environments` is disabled.
Create new fields	If this permission is not granted, the user cannot see the `Fields` side panel in the schema builder.
Create new models	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but will not be able to use the `+ Add` button to create new models.
Create new roles	If this permission is not granted, the user cannot see the option to add a custom role in the UI.
Create new webhooks	If this permission is not granted, the user cannot see the `+ Add webhook` button.
Create public content views	Enable this permission to allow users to create custom content views in the content editor. If this permission is not granted, users won't see the `Add custom view` button at the top of the screen.
Create public view groups	This permission grants users the ability to create view groups.
Create remote sources	If this permission is not granted to a user who has the `Can see schema view` permission, they will be able to access the Schema builder, but will not be able to see the `+ Add` button to create new remote sources.
Create stages	This permission allows users to see the `+ Add` stage button in `Project Settings > General > Content Stages`.
Delete an existing environment	If this permission is not granted, the `Delete` and `Promote to master` options in `Project Settings > General > Environments` are disabled.
Delete an existing environment backup	This permission allows deleting an existing environment backup.
Delete an existing role	If this permission is not granted, the user cannot see the `Delete` option for custom roles.
Delete an existing webhook	This permission grants users the ability to see the `Delete` option for webhooks.
Delete existing components	If this permission is not granted, the user cannot see the `Delete` option inside a component's context menu.
Delete existing entries	This permission grants you the ability to delete entries. If this is not selected, you will not see the `Delete` button.
Delete existing enumerations	This permission allows users to delete enumerations. If this permission is not granted, users can't see the `Delete` option inside the context menu at the top of the enumeration details screen.
Delete existing fields	This permission allows users to see the `Delete` option inside the context menu of the fields added to a model in the Schema builder and delete the field. Users must be able to read the schema and models to reach this screen.
Delete existing models	If this permission is not granted, the user cannot see the `Delete` option for models in the UI.
Delete locales	This permission allows users to delete locales in a project. If this permission is not granted, users cannot use the `Delete` button next to locales in `Project Settings > General > Locales`.
Delete public content views	This permission allows the user to delete custom views. If this permission is not granted, users cannot see the `Delete custom view` option inside the context menu at the top of the custom view screen.
Delete public view groups	If this permission is not granted, the user will get logged out when attempting to use the `Delete` button for public view groups.
Delete remote sources	If this permission is not granted, users cannot see the `Delete` option for remote sources.
Delete stages	If this permission is not granted, the `Delete` option in `Project Settings > General Content Stages` will throw an error when the user clicks on it.
Invite a user into an existing project	If this permission is not granted, the user cannot see the `Invite members` button in `Project Settings > Team > Members`.
Promote an existing environment	If this permission is not granted, the user will get an error when using the `Promote to master` button in `Project Settings > General > Environments`.
Publish non-published entries	This permission allows users to publish entries that exist only in the `DRAFT` stage (entries that have been saved but never published).
Read audit logs	If this permission is not granted, users cannot see the `Audit logs` tab in Project Settings.
Read existing environment backups and their details	This permission allows reading existing environment backups and their details.
Read existing webhooks	If this permission is not granted, the user cannot see the Webhooks tab in Studio's main navigation
Remove a user from an existing project	This permission grants users the ability to see the `Remove` option for users.
Restore an existing environment backup to a standard environment	This permission allows restoring an existing environment backup to a standard environment.
Update an existing environment	This permission grants the ability to edit environments through the API.
Update an existing environment backup	This permission allows updating an existing environment backup.
Update existing components	This permission grants users the ability to edit the information in the `Settings` tab of components. To reach this screen, users will need permissions to read the schema and models. If an entry is in the `DRAFT` stage, you can update and save it, but as soon as it's updated, if you do not have permission to update published entries, you won't be able to keep working on it.
Update existing enumerations	This permission grants users the ability to edit enumeration details. To reach this screen, users will need permissions to read the schema and enumerations.
Update existing fields	This permission allows users to see the `Edit` button on the field cards in models, and edit the field details. Users must be able to read the schema and models to reach this screen. If this permission is not granted, users cannot see the `Edit field` button, and the drag-and-drop anchor is not displayed.
Update existing models	This permission grants users the ability to edit the information in the `Settings` tab of models. To reach this screen, users will need permissions to read the schema and models.
Update existing non published entries	This permission allows the user to save a content entry without publishing. If this permission is disabled, the user won't see the `Save` button at the top-right corner of content entries and will only see the `Publish` button.
Update existing webhooks	If this permission is not granted, the user cannot see the `Edit` button for webhooks.
Update published entries	This permission grants you the ability to update published entries. If this is not selected, when an entry is published, you do not see the `Save` button.
Update stages	If this permission is not granted, the user cannot see the `Content stages` option in their project settings.
Update system content views	If this permission is not granted, the user cannot see the `Update default view` in the Content editor and in Assets.
Update existing roles	If this permission is not granted, the user can open all existing roles, but all update-related buttons will be hidden, and they will get an error when attempting to edit content permissions.
Update locales	This permission allows users to edit locales in a project. If this permission is not granted, when users go to `Project Settings > General > Locales`, they will find that the locales are read-only and are grayed out.
Update public content views	This permission allows the user to edit custom views. If this permission is not granted, users cannot see the `Edit` custom view option inside the context menu at the top of the custom view screen.
Update public view groups	If this permission is not granted, you cannot update view groups.
Update remote sources	This permission grants users the ability to edit the information in the `Settings` tab of remote sources. To reach this screen, users will need permissions to read the schema and remote sources. If this permission is not granted, the user can reach the `Settings` screen, but the `Save` button is hidden.

#Permanent Auth Tokens

If you create a Permanent Auth Token and initialize default permissions, these permissions will let you create models, fields, components, and enumerations, as well as read models, fields, components, enumerations, content stages, locales, and environments.

As a result, if you need to be able to delete or update schema elements, you will have to add those permissions manually.

For instance, to work with the Management SDK, you need to make sure that you have create, update, delete, read Management API permissions on for all the things you may want to update on the schema. Our granular permissions would allow you to grant total or partial access.

Typically, an Auth Token doesn't interact with the UI, so UI-related permissions are not included in the default permissions you can automatically initialize.

In this case, giving any UI-related permissions would not have an impact on what you can do. A good example of this is the Create new entries Management API permission. Despite it being a Management API permission, it only controls what users assigned to a role can see in the UI.

You cannot create content entries with the Management API because the Content API handles that. So, if you need a Management API token to use the Management SDK to create content, adding that permission won't really change anything because the actual permission to perform the action comes from the Content API, and programmatic content creation does not use the UI.

#Default PAT permissions

PERMISSION	DESCRIPTION
Create new models	This permission is necessary to create models through the API.
Read existing fields	This permission is necessary to access fields information through the API.
Read existing enumerations	This permission is necessary to access enumerations information through the API.
Read locales	This permission is necessary to access locales information through the API.
Create new fields	This permission is necessary to create fields through the API.
Create new components	This permission is necessary to create components through the API.
Read existing components	This permission is necessary to access locales information through the API.
Create new enumerations	This permission is necessary to create new enumerations through the API.
Read existing environments	This permission is necessary to access environments information through the API.
Read remote sources	This permission is necessary to access remote sources information through the API.
Read stages	This permission is necessary to access stages information through the API.
Create remote sources	This permission is necessary to create new remote sources through the API.
Read existing models	This permission is necessary to access models information through the API.

#Additional PAT permissions

PERMISSION	DESCRIPTION
Assign a role to a user	This permission is necessary to assign roles to users in a project.
Can add app installations	This permission is necessary to install apps.
Can add new integrations to an existing project	This permission is necessary to install apps.
Can create content permissions	This permission is necessary to create content permissions.
Can create new permanent auth tokens	This permission is necessary to create new PATs.
Can delete app installations	This permission is necessary to delete apps.
Can delete content permissions	This permission is necessary to delete content permissions.
Can delete existing integrations in an existing project	This permission is necessary to delete apps.
Can delete existing permanent auth tokens	This permission is necessary to delete existing PATs.
Can read existing permanent auth tokens	This permission is necessary to access existing PATs information through the API.
Can read content permissions	This permission is necessary to access content permissions information through the API.
Can see Role & Permissions Settings	This permission is necessary to access roles & permissions information.
Can see schema view	View permission that allows a user to see the Schema builder. You can choose to deselect this permission to hide the schema view for roles for which it's not relevant.
Can see Team Member Settings	View permission that allows users to see the `Members` tab in `Project Settings > Team`.
Can update app installations	This permission is necessary to delete app installations.
Can update content permissions	This permission is necessary to update content permissions.
Can update existing permanent auth tokens	This permission is necessary to update PATs.
Can use the playground	View permission that allows users to see the API Playground in the UI.
Change the name, picture and description of a project	This permission is necessary to update project details.
Create a new environment backup	This permission allows creating a new environment backup.
Create locales	This permission is necessary to create project locales.
Create new entries	View permission that allows the user to see the `+ Add entry` button at the top right corner of the content editor screen.
Create new environment	This permission is necessary to create new environments in a project.
Create new roles	This permission is necessary to create new roles through the API.
Create new webhooks	This permission is necessary to create new webhooks.
Create public content views	This permission is necessary to create public content views.
Create public view groups	This permission is necessary to create public view groups.
Create stages	This permission is necessary to create custom content stages.
Delete an existing environment	This permission is necessary to delete existing environments.
Delete an existing role	This permission is necessary to delete existing roles.
Delete an existing webhook	This permission is necessary to delete existing webhooks.
Delete locales	This permission is necessary to delete locales from a project.
Delete an existing environment backup	This permission allows deleting an existing environment backup.
Delete existing components	This permission is necessary to delete existing components.
Delete existing entries	View permission that allows user to see the `Delete` option for entries in the UI.
Delete existing enumerations	This permission is necessary to delete existing enumerations.
Delete existing fields	This permission is necessary to delete existing schema fields.
Delete existing models	This permission is necessary to delete existing models.
Delete public content views	This permission is necessary to delete public content views.
Delete public view groups	This permission is necessary to delete public view groups.
Delete remote sources	This permission is necessary to delete remote sources from a project.
Delete stages	This permission is necessary to delete content stages in a project.
Invite a user into an existing project	This permission is necessary to invite new users to an existing project.
Promote an existing environment	This permission is necessary to promote an existing environment.
Publish non published entries	View permission that allows users to publish entries that exist only in the `DRAFT` stage (entries that have been saved but never published).
Read audit logs	This permission is necessary to access audit logs information.
Read existing entries	View permission that allows users to see the Content and Assets tabs in the UI.
Read existing environment backups and their details	This permission allows reading existing environment backups and their details.
Read existing webhooks	This permission is necessary to access information about existing webhooks.
Read public content views	This permission is necessary to access public content views information.
Read public view groups	This permission is necessary to access public view groups information through the API.
Remove a user from an existing project	This permission is necessary to delete users from a project.
Restore an existing environment backup to a standard environment	This permission allows restoring an existing environment backup to a standard environment.
Update an existing environment	This permission is necessary to update existing environments.
Update an existing environment backup	This permission allows updating an existing environment backup.
Update existing components	This permission is necessary to run update existing components.
Update existing enumerations	This permission is necessary to update existing enumerations in a project schema.
Update existing non published entries	View permission. If an entry is in the `DRAFT` stage, you can update and save, but as soon as it's updated, if you do not have the permissions to update published entries, you won't be able to keep working on it.
Update existing fields	This permission is necessary to update existing fields in the schema.
Update existing models	This permission is necessary to update existing models.
Update existing roles	This permission is necessary to update existing roles.
Update existing webhooks	This permission is necessary to update existing webhooks.
Update locales	This permission is necessary to update project locales.
Update public content views	This permission is necessary to update public content views.
Update public view groups	This permission is necessary to update public view groups.
Update published entries	View permission that allows a user to see the `Save` button in the content creation screen.
Update stages	This permission is necessary to update stages.
Update system content views	This permission is necessary to update system content views.
Update remote sources	This permission is necessary to update remote sources in a project.