# Permissions System

## Introduction 

The following document describes how the permission system works at Kyso, which is highly customisable, in which we can create roles with fine-grained permissions to configure how your users can behave on the platform. 

## Platform Roles 

Kyso has default access controls on deployment. Below is a list of the predefined roles called **platform roles**. These roles are the most common ones, and are “self-explanatory”. The roles are the following:

* Platform / Account Admin
* Organization Admin
* Channel / Team Admin
* Channel Contributor
* Channel Reader

{% hint style="info" %}
Channels and Teams mean the same thing on Kyso so might be used interchangeably across the public documentation and Git repositories.
{% endhint %}

## Role Access Levels

### Table Legend

* 🎷 -> Only for the entities that the user owns or belongs to (comments, reports, repos, organizations, etc.). That means that users can’t perform these actions in other channels/discussions/reports/etc. in which he/she is not a member of nor owns it.
* 🔓 -> Only public channels accessed directly with the URL.

![Legend Part 1](https://4003540104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LjzfPqQ1fXmC4OMXwiD%2Fuploads%2Fnp0tQBhupIAhdIsohLi2%2Froles1.png?alt=media\&token=9611de1f-212a-47a6-b55c-abda8912c30d)

![Legend Part 2](https://4003540104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LjzfPqQ1fXmC4OMXwiD%2Fuploads%2FKFtUGKXaTLIdzL4T4t3B%2Froles2.png?alt=media\&token=b9a072c9-47a5-4d84-bdde-1e21ad0877e4)

![Legend Part 3](https://4003540104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LjzfPqQ1fXmC4OMXwiD%2Fuploads%2F8jlwXqw6XjuW4vxIDnBm%2Frole3.png?alt=media\&token=f98e132d-6e16-4034-836c-cb2ad27b7194)

![Legend Part 4](https://4003540104-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LjzfPqQ1fXmC4OMXwiD%2Fuploads%2FTcvFsQFSgjDweaHxuUpL%2Frole4.png?alt=media\&token=96e4ee13-0be1-4d30-af51-6002d4434b12)

## Platform Organisational Structure

### 1. Organizations

An **organization** is a management unit at Kyso to manage the permissions and the behaviour of users that belong to it. Consider that:

* Every user belongs to at least one organization
  * Every time a new user is created at Kyso, a new organization “{{username}}’s Workspace” is created (i.e. this is their personal workspace)
* A user can belong to more than one organization.

### 2. Channels / Teams

A **channel** is a management unit at Kyso, to manage the visibility and the behaviour of the users. Consider that:

* Every user belongs to at least one channel
  * Every time a new user is created, a new channel “{{usernames}}’ Private Team” is created and linked to “{{usernames}}’s Workspace”
* A user can belong to more than one channel
* A channel can be:
  * **Public**: Every user on the company's Kyso account can access that channel.
  * **Protected**: Only users that belong to the organization that owns the channel can access that channel.
  * **Private**: Only users with a specific invitation can access that channel

### 3. Reports

A **report** is an instance of an imported notebook (Jupyter, etc.) or other file type. All the data, comments, collaboration, etc. is done inside a report. Consider that:

* Every report belongs to a channel.

## Custom Roles 

The permission system allows the creation of new roles, with a specific bunch of permissions, in organization and channel scopes. 

{% hint style="info" %}
Contact our Support team for more info on this!
{% endhint %}

That means:

* An organization admin can create a new role that is only valid inside its organization
  * Then, the users that belong to that organization can be configured to use:
    * All the Platform Roles
    * The custom roles of that organization
* A channel admin can create a new role that is only in valid inside its channel.
  * Then the users that belong to that channel can be configured to use:
    * All the Platform Roles
    * The custom roles of the organization that owns the channel (if there is one)
    * The custom roles of that channel

## Authorization Hierarchy 

```md
.
└── Platform Roles
    └── Organization Roles
        └── Channel/Team Roles
```