diff --git a/docs/settings/computational_resources.mdx b/docs/settings/computational_resources.mdx
index dfe3e60..4b65eef 100644
--- a/docs/settings/computational_resources.mdx
+++ b/docs/settings/computational_resources.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 6
 description: "Computational Resources"
 keywords: ["domino", "workflow", "airflow", "data", "machine learning", "ml", "data science", "data engineering", "dataops", "mlops", "devops", "kubernetes", "k8s", "helm", "python", "react", "typescript", "fastapi", "gitops", "docker", "github", "artifacthub", "pypi", "pip", "kind", "open source", "oss", "low code", "no code", "automation",
 "versio control", "collaboration", "monitoring", "orchestration", "data pipeline", "computational", "resources"]
diff --git a/docs/settings/github_token.md b/docs/settings/github_token.md
index b40ee62..b955aa6 100644
--- a/docs/settings/github_token.md
+++ b/docs/settings/github_token.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 # Authorize access to Github repositories
diff --git a/docs/settings/installing_repositories.mdx b/docs/settings/installing_repositories.mdx
index 9d7eb0d..7a03b19 100644
--- a/docs/settings/installing_repositories.mdx
+++ b/docs/settings/installing_repositories.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Install Pieces repositories
diff --git a/docs/settings/secrets.md b/docs/settings/secrets.md
index 58bcc55..c0284bc 100644
--- a/docs/settings/secrets.md
+++ b/docs/settings/secrets.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 description: "Pieces Repositories Secrets"
 keywords: ["domino", "workflow", "airflow", "data", "machine learning", "ml", "data science", "data engineering", "dataops", "mlops", "devops", "kubernetes", "k8s", "helm", "python", "react", "typescript", "fastapi", "gitops", "docker", "github", "artifacthub", "pypi", "pip", "kind", "open source", "oss", "low code", "no code", "automation", "versio control", "collaboration", "monitoring", "orchestration", "data pipeline", "secrets"]
 ---
diff --git a/docs/settings/shared_storage.mdx b/docs/settings/shared_storage.mdx
index 372ceca..e228d56 100644
--- a/docs/settings/shared_storage.mdx
+++ b/docs/settings/shared_storage.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 5
 description: "Shared Storage"
 keywords: ["domino", "workflow", "airflow", "data", "machine learning", "ml", "data science", "data engineering", "dataops", "mlops", "devops", "kubernetes", "k8s", "helm", "python", "react", "typescript", "fastapi", "gitops", "docker", "github", "artifacthub", "pypi", "pip", "kind", "open source", "oss", "low code", "no code", "automation", "versio control", "collaboration", "monitoring", "orchestration", "data pipeline", "shared storage"]
 ---
diff --git a/docs/settings/workspaces.md b/docs/settings/workspaces.md
new file mode 100644
index 0000000..1ca2c68
--- /dev/null
+++ b/docs/settings/workspaces.md
@@ -0,0 +1,49 @@
+---
+sidebar_position: 1
+description: "Workspaces"
+keywords: ["domino", "workflow", "airflow", "data", "machine learning", "ml", "data science", "data engineering", "dataops", "mlops", "devops", "kubernetes", "k8s", "helm", "python", "react", "typescript", "fastapi", "gitops", "docker", "github", "artifacthub", "pypi", "pip", "kind", "open source", "oss", "low code", "no code", "automation", "versio control", "collaboration", "monitoring", "orchestration", "data pipeline", "secrets"]
+---
+
+
+
+# Workspaces
+
+Workspaces are the main organizational unit in Domino. They are used to group workflows, users, secrets and pieces repositories. Each workspace has its own permissions and settings.
+
+
+# Permissions
+Within a workspace, users can have the following permissions: `owner`, `admin`, `write` and `read`. Permissions are a means of controlling and regulating access to specific functions at the system level.
+
+## Read
+
+  * can see workspace pieces
+  * can see workflows runs
+  * can see workflows results
+
+## Write
+
+All `read` permissions and:
+
+* can create workflow
+* can remove workflow
+* can trigger workflow manually (if the workflow are active)
+
+## Admin
+
+All `read` and `write` permissions and:
+
+* can invite/remove users (except for admins and owner)
+* can create/remove workflows
+* can trigger workflow manually
+* can add/edit/remove secrets
+* can add/edit/remove pieces
+
+
+## Owner
+
+Unique per workspace.
+
+All `read`, `write` and `admin` permissions and:
+
+* can delete the workspace
+* can invite/remove users (including admins)