diff --git a/docs/security/custom-roles.md b/docs/security/custom-roles.md
new file mode 100644
index 00000000..2d49a51e
--- /dev/null
+++ b/docs/security/custom-roles.md
@@ -0,0 +1,37 @@
+---
+Description: Custom roles for Semaphore platform.
+---
+
+# Custom Roles
+
+If your organization needs more roles where permissions would be assigned with 
+higher granularity, you can define custom roles.
+
+### Creating a new role
+
+When defining a custom role, you need to give it a unique name (that does not clash
+with any of the default roles) and select which [permissions](/security/permissions/) will
+its users have. Role inheritance is also allowed, so you can create a new role
+**Sys Admin** that will have all the same permissions as **Developer**, for example,
+plus access to Self hosted agents (`organization.self_hosted.create`). Permissions
+for the Sys Admin role are determined "dynamically", so if you later modify the Developer role
+and add/remove some permissions from it, the Sys Admin role will reflect those
+changes.
+
+**TODO** Picture of UI for creating new role, when the ui gets made
+
+### Organization role to project role mapping
+
+If there is any role within the organization that needs to have access to all of the
+projects, you can define an "*org-role to project-role mapping*" for it. If you want your
+Sys Admins to have Admin level access to all of the projects, you can say that the Sys Admin role
+maps to the project Admin role.
+
+!!! warning "Note"
+    Custom roles are currently only available on our [enterprise plan](pricing).
+
+!!! info "Default Roles"
+    As an organization that has Custom Roles enabled, you will still have access to the default roles as well.
+
+Do you need Custom roles in order to use Semaphore? Contact us via this [form](/contact)
+
diff --git a/docs/security/permissions.md b/docs/security/permissions.md
new file mode 100644
index 00000000..dc475eda
--- /dev/null
+++ b/docs/security/permissions.md
@@ -0,0 +1,188 @@
+---
+Description: Page containing a list of all permissions within the Semaphore.
+---
+
+# Permissions
+
+This page lists all permissions within the Semaphore system. It will be 
+of use when creating custom roles and defining what they can do. 
+
+As with the roles, permissions are also divided into **organization-level**
+and **project-level**.
+
+!!! info "Note"
+    Some permissions are not yet part of Semaphore but will be introduced in the near future. Those are marked with **✕**
+
+
+## Organization permissions
+
+<br />
+#### Organization secrets [↗](/essentials/using-secrets/)
+
+`organization.secrets.view`<br />
+<span style="font-size:smaller;">Following permissions are related to
+[secrets management](/essentials/using-secrets/#creating-and-managing-secrets).</span><br />
+`organization.secrets.create`<br />
+`organization.secrets.modify`<br />
+`organization.secrets.delete`<br />
+
+#### Audit logs [↗](/security/audit-logs/)
+
+`organization.audit_logs.view`<br />
+`organization.audit_logs.export` [↗](/security/audit-logs-exporting/)<br />
+`organization.audit_logs.streaming.view` [↗](/security/audit-logs-exporting/#streaming)<br />
+`organization.audit_logs.streaming.manage`<br />
+
+#### Self-hosted agents [↗](/ci-cd-environment/self-hosted-agents-overview/)
+
+`organization.self_hosted_agents.view`<br />
+`organization.self_hosted_agents.create`<br />
+`organization.self_hosted_agents.reset_token`<br />
+`organization.self_hosted_agents.disable`<br />
+`organization.self_hosted_agents.delete`<br />
+
+#### General settings
+
+`organization.general_settings.view`<br />
+`organization.general_settings.modify`<br />
+
+#### Organizational notifications [↗](/essentials/webhook-notifications/)
+
+`organization.notifications.view`<br />
+`organization.notifications.create`<br />
+`organization.notifications.modify`<br />
+`organization.notifications.delete`<br />
+
+#### Organizational pre-flight checks [↗](/essentials/configuring-pre-flight-checks/)
+
+`organization.pre_flight_checks.view`<br />
+`organization.pre_flight_checks.modify`<br />
+
+#### Billing
+
+`organization.plans_and_billing.view`<br />
+`organization.plans_and_billing.modify`<br />
+
+#### Dashboards [↗](/essentials/deployment-dashboards/)
+
+<span style="font-size:smaller;">These permissions don't control whether or not you can see deployment pipelines
+defined by the dashboards, but rather if you can access and modify the definition of those
+dashboards using `sem` cli tool like it is shown [here](/essentials/deployment-dashboards/#creating-a-dashboard).</span><br />
+`organization.dashboards.view`<br />
+`organization.dashboards.create`<br />
+`organization.dashboards.modify`<br />
+`organization.dashboards.delete`<br />
+
+#### Managing people
+
+`organization.people.view`<br />
+`organization.people.invite`<br />
+`organization.people.remove`<br />
+`organization.people.change_role`<br />
+
+#### Role management **✕**
+
+`organization.roles.view`<br />
+`organization.roles.create`<br />
+`organization.roles.remove`<br />
+`organization.roles.modify`<br />
+
+#### Managing how repository access levels map to Semaphore project roles **✕**
+
+`organization.repo_to_role_mappers.view`<br />
+`organization.repo_to_role_mappers.create`<br />
+`organization.repo_to_role_mappers.delete`<br />
+`organization.repo_to_role_mappers.modify`<br />
+
+#### Other permissions
+
+`organization.projects.create`<br />
+`organization.activity_monitor.view`<br />
+
+## Project permissions
+
+<br />
+#### Managing people
+
+`project.people.change_role`<br />
+`project.people.remove`<br />
+`project.people.invite`<br />
+
+#### Accessing/running jobs
+
+`project.job.view`<br />
+`project.job.rerun`<br />
+`project.job.artifacts.view`<br />
+`project.job.artifacts.delete`
+<span style="font-size:smaller;">(Grants permissions for [job level](/essentials/artifacts/#job-artifacts) artifacts)</span><br />
+`project.job.stop`<br />
+<span style="font-size:smaller;">Follwing permissions are needed to
+access jobs via `sem` [cli tool](/reference/sem-command-line-tool/#operations).</span><br />
+`project.job.port_forwarding`<br />
+`project.job.attach`<br />
+`project.job.debug`<br />
+`project.debug`<br />
+
+#### Project level secrets **✕**
+
+`project.secrets.view`<br />
+`project.secrets.create`<br />
+`project.secrets.modify`<br />
+`project.secrets.delete`<br />
+`project.authorized_org_secrets.list`<br /> <span style="font-size:smaller;">(List of organization level secrets
+that are whitelisted to be used within the given project)</span><br />
+
+#### Project notifications **✕**
+
+`project.notifications.view`<br />
+`project.notifications.create`<br />
+`project.notifications.modify`<br />
+`project.notifications.delete`<br />
+
+#### Schedulers [↗](/essentials/schedule-a-workflow-run/)
+
+`project.scheduler.view`<br />
+`project.scheduler.create`<br />
+`project.scheduler.delete`<br />
+`project.scheduler.modify`<br />
+`project.scheduler.run_manually`<br />
+`project.scheduler.deactivate`<br />
+
+#### Workflow
+
+`project.workflow.view`<br />
+`project.workflow.modify`<br />
+`project.workflow.rerun`<br />
+`project.workflow.stop`<br />
+`project.workflow.artifacts.view `<br />
+<span style="font-size:smaller;">(Grants permissions for [workflow level](/essentials/artifacts/#workflow-artifacts) artifacts)</span><br />
+`project.workflow.artifacts.delete`<br />
+
+#### Artifacts [↗](/essentials/artifacts/)
+
+`project.artifacts.delete`<br />
+`project.artifacts.view`<br />
+`project.artifacts.view_settings`
+<span style="font-size:smaller;">(Grants permissions for [project level](/essentials/artifacts/#project-artifacts) artifacts)</span><br />
+`project.artifacts.modify_settings`<br />
+
+#### Project pre-flight checks [↗](essentials/configuring-pre-flight-checks/#project-pre-flight-checks)
+
+`project.pre_flight_checks.view`<br />
+`project.pre_flight_checks.modify`<br />
+
+#### Project insights 
+
+`project.insights.view`<br />
+`project.insights.modify`<br />
+
+#### Project settings and other permissions
+
+`project.view`<br />
+`project.delete`<br />
+`project.general_settings.view`<br />
+`project.general_settings.modify`<br />
+`project.repository_info.view`<br />
+`project.repository_info.modify`<br />
+`project.badge.view`<br />
+`project.badge.manage`<br />
diff --git a/mkdocs.yml b/mkdocs.yml
index 14a8d811..15eabcdd 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -233,6 +233,8 @@ nav:
     - "User authorization":
       - RBAC overview: security/rbac-authorization.md
       - Default roles: security/default-roles.md
+      - Custom roles: security/custon-roles.md
+      - Permissions: security/permissions.md
       - Repository-to-role mappings: security/repository-to-role-mappings.md
   - Score:
       - Insights: score/project-insights.md