Repository: SimpleDataLabsInc/prophecy-docs
Pull request #626: Team-based access documentation
Author: login: kathweinschenkprophecy
Created: 2025-04-25T16:05:29Z | Merged: 2025-04-28T17:13:24Z



---
- To see the specific tasks where the Asana app for GitHub is being used, see below:
  - https://app.asana.com/0/0/1210060333324744


Diff:
diff --git a/docs/administration/access-control/change-password.md b/docs/administration/access-control/change-password.md
deleted file mode 100644
index ceb607e3f48..00000000000
--- a/docs/administration/access-control/change-password.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: Change password
-id: change-password
-draft: true
-description: Change your Prophecy account password
-tags: []
----
diff --git a/docs/administration/access-control/team-based-access.md b/docs/administration/access-control/team-based-access.md
deleted file mode 100644
index 317db815d55..00000000000
--- a/docs/administration/access-control/team-based-access.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: Team-based access
-id: team-based-access
-draft: true
-description: Manage access by team
-tags: []
----
-
-In Prophecy, access control is managed at the team level. Each user belongs to a team, and permissions are granted based on team membership. Team admins have special team privileges, and there can be multiple team admins configured per team.
-
-## Projects and fabrics
-
-Teams can own many projects and fabrics, but each project and fabric can only be assigned to one team.
-
-## Share project access
-
-If a project is shared with you, you can use its components from the package hub in a read-only manner. This means you can reference and incorporate transformations, datasets, and other reusable assets from the project without modifying them.
-
-This approach ensures that core business rules and standard transformations remain consistent across teams. By preventing direct edits, organizations can maintain data integrity, enforce best practices, and avoid fragmentation of logic across multiple projects.
-
-## Restrict pipeline editing
-
-Business apps enable users to execute pipelines without needing full access to modify them. If a project containing a business app is shared with you, you can run the app but cannot edit the underlying pipelines, datasets, or configurations.
-
-This restriction is beneficial for operational teams that need to trigger workflows without risking unintended changes. It also helps maintain compliance by ensuring that only authorized developers can alter critical business logic while still allowing users to execute necessary processes.
diff --git a/docs/administration/teams-users/img/Access_Settings_page.png b/docs/administration/teams-users/img/Access_Settings_page.png
index 87a8ca48a0e..9c9cd1b4043 100644
Binary files a/docs/administration/teams-users/img/Access_Settings_page.png and b/docs/administration/teams-users/img/Access_Settings_page.png differ
diff --git a/docs/administration/teams-users/img/fabric-dev.png b/docs/administration/teams-users/img/fabric-dev.png
new file mode 100644
index 00000000000..1453f4e2fce
Binary files /dev/null and b/docs/administration/teams-users/img/fabric-dev.png differ
diff --git a/docs/administration/teams-users/img/fabric-prod.png b/docs/administration/teams-users/img/fabric-prod.png
new file mode 100644
index 00000000000..a590e9c4303
Binary files /dev/null and b/docs/administration/teams-users/img/fabric-prod.png differ
diff --git a/docs/administration/teams-users/img/project-fabric-attachment.png b/docs/administration/teams-users/img/project-fabric-attachment.png
new file mode 100644
index 00000000000..efd883359a3
Binary files /dev/null and b/docs/administration/teams-users/img/project-fabric-attachment.png differ
diff --git a/docs/administration/teams-users/img/project-fabric-team.png b/docs/administration/teams-users/img/project-fabric-team.png
new file mode 100644
index 00000000000..adfb7723d4b
Binary files /dev/null and b/docs/administration/teams-users/img/project-fabric-team.png differ
diff --git a/docs/administration/teams-users/settings.md b/docs/administration/teams-users/settings.md
index 27622967c0e..4335acf49dc 100644
--- a/docs/administration/teams-users/settings.md
+++ b/docs/administration/teams-users/settings.md
@@ -1,8 +1,7 @@
 ---
 title: User settings
 id: settings
-sidebar_class_name: hidden
-description: This page describes the Settings pages of Prophecy
+description: Learn about the different Prophecy settings to configure
 tags:
   - settings
   - admin
@@ -10,46 +9,67 @@ tags:
   - teams
 ---
 
-This page talks about the User's Settings and preferences.
+Prophecy settings are applied at the user level. You can change settings to:
 
-To access Settings, click on the `...` at the bottom of the left-hand menu bar and then click the Settings icon, as shown below.
+- Update your personal user profile.
+- Manage your teams and team members.
+- Add, edit, or delete Git credentials from your environment.
+- Set up authentication.
+- View the current version of your Prophecy environment.
+
+Navigate to settings by clicking `...` in the left navigation menu and the **gear** icon.
 
 ![access-settings](img/Access_Settings_page.png)
 
-## Info
+:::note
+Prophecy cluster admins will see an additional **Admin** tab in settings.
+:::
+
+## Settings tabs
+
+### Info
 
-Users can manage their account Name, Email, and Password from the Info Tab. They can also delete their Account if needed.
+In the **Info** tab, you can:
 
-![user-settings](img/User_Settings.png)
+- Update your name
+- Update your company
+- Change your password
+- Delete your account
 
-:::caution Deleting an account
-It's important to note that this action is irreversible. Once you delete an account, all associated data will be permanently removed from Prophecy.
-Be aware that all personal teams, projects, and fabrics will be permanently deleted and cannot be recovered.
+:::caution
+Deleting an account is irreversible. Once you delete an account, all associated data will be permanently removed from Prophecy, including personal teams, projects, and fabrics.
 :::
 
-## Teams
+### Teams
 
-This page displays all the Teams the current user is a part of. From here, you can Create a new team or invite Users to your existing Teams.
+In the **Team** tab, you can:
 
-![Teams](img/Teams.png)
+- View teams that you are included in
+- Create new teams
+- View users in your teams
+- Add users to or delete users from your teams
+- Modify user roles (for example, making a user a team admin)
 
-## Git
+### Git
 
-This page displays the Git credentials created by the user. By default, a credential for Prophecy Managed Git is present. These tokens are linked to Prophecy projects each user accesses.
+In the **Git** tab, you can:
 
-![git](img/Git.png)
+- Review your existing Git credentials (Prophecy-Managed Git is present by default)
+- Add new Git credentials
+- Edit or delete existing Git credentials
 
-## Access Token
+These credentials can be used during project creation. Git connections are required to store Prophecy project metadata and code.
 
-This page displays the Personal Access Tokens created to access Prophecy APIs securely.
+### Access Token
 
-![Access_tokens](img/Access_Tokens.png)
+In the **Access Token** tab, you can:
 
-## About
+- Review active or inactive Personal Access Tokens
+- Create new Personal Access Tokens to access Prophecy APIs securely
 
-This page displays the current version and state of all services in Prophecy deployment.
+### About
 
-![About](img/About.png)
+The **About** tab displays the current version of the Prophecy deployment.
 
 ## What's next
 
diff --git a/docs/administration/teams-users/team-based-access.md b/docs/administration/teams-users/team-based-access.md
new file mode 100644
index 00000000000..317b869e4d7
--- /dev/null
+++ b/docs/administration/teams-users/team-based-access.md
@@ -0,0 +1,157 @@
+---
+title: Team-based access
+id: team-based-access
+description: Manage access by team
+tags: []
+---
+
+In Prophecy, access control operates through team associations with resources. Projects and fabrics are the fundamental resources to which teams are assigned. Users who belong to a team can access all projects and fabrics assigned to that team.
+
+![Relationship between users, teams, projects, and fabrics](img/project-fabric-team.png)
+
+This guide provides comprehensive best practices for implementing and managing team-based access to optimize collaboration while maintaining appropriate security boundaries.
+
+:::note
+Team admins have special privileges for managing team membership, but the core access model remains focused on the team-to-resource relationship. Each team can be assigned to many projects and fabrics, but importantly, each project and fabric can only be assigned to one team.
+:::
+
+## Team structure
+
+The way you structure your teams will fundamentally shape how users interact with data and resources in Prophecy. There are several approaches to team organization, each with its own advantages depending on your organization's needs.
+
+In any case, teams should be assigned only to the resources they genuinely need to access. This principle minimizes the potential impact of compromised credentials and reduces the risk of accidental data modifications.
+
+### Strategy 1: Environment-based teams
+
+One of the most straightforward approaches is to split teams based on access to development and production environments. This creates a clear separation between experimentation and production workloads.
+
+#### Dev Team (All Users)
+
+- Limited access to data
+- Access to development environment(s) only
+- Allows for safe experimentation and testing
+
+#### Prod Team (Platform Team Only)
+
+- Complete access and control to production environment
+- Restricted to users responsible for production operations
+- Ensures controlled deployment to production
+
+### Strategy 2: Function-based teams
+
+As organizations scale, they often benefit from more granular team structures aligned with specific job functions. This approach allows for more precise resource allocation and specialized access patterns tailored to different roles within the data ecosystem. Here we provide one example of function-based teams.
+
+#### Data Engineering Team
+
+- Access to all environments, especially with raw data
+- Design and build data pipelines
+- Manage data quality and optimization
+
+#### Marketing Analytics Team
+
+- Access to environment with web analytics and campaign data
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+#### Product Analytics Team
+
+- Access to environment with user behavior data and product metrics
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+## Fabric creation
+
+Fabrics are the bridge between Prophecy and your execution environment. They encapsulate connection details and access credentials, making them a critical component of your security architecture. Thoughtfully configured fabrics ensure that the right people have the right level of access to your data processing resources.
+
+:::note
+Authentication capabilities vary between different connection types across fabrics. Visit individual connection documentation to learn about the specific authentication strategies available for that connection.
+:::
+
+### Development fabrics
+
+Development fabrics should be configured to facilitate collaborative work and allow for experimentation.
+
+- **Team assignment**: Dev team
+- **Connection authentication**: Individual authentication
+- **Benefits**: Maintains accountability with each run linked to an individual identity
+- **Usage**: For projects in development phase only
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for development.
+
+![Development fabric](img/fabric-dev.png)
+
+### Production fabrics
+
+Production fabrics require a different approach focused on stability and reliability. These environments run your business-critical processes and must operate consistently without frequent intervention.
+
+- **Team assignment**: Prod team
+- **Authentication**: Service principal
+- **Benefits**: Eliminates reauthentication needs and ensures smooth job execution
+- **Usage**: For scheduled pipelines in deployed projects
+
+Using service principals for production fabrics ensures that scheduled jobs continue to run even when individual team members are unavailable or their credentials change.
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for production.
+
+![Production fabric](img/fabric-prod.png)
+
+## Project management
+
+Projects in Prophecy encapsulate data pipelines, gems, tables, and other components. How you structure and assign these projects to teams will differ between use cases.
+
+When you first begin using Prophecy, you can create projects with personal team for experimentation, then migrate to collaborative projects organized by business objectives:
+
+- **Create purpose-specific projects**: "Marketing Analytics," "Customer Retention," etc.
+- **Align with team structure**: Ensure projects are assigned to appropriate teams
+- **Document project scope**: Define project boundaries and ownership
+
+Purpose-specific projects help maintain focus and prevent the sprawl of unrelated components within a single project. By clearly defining each project's boundaries, teams can more easily understand what belongs where and how different components relate to business objectives.
+
+### Sharing and collaboration
+
+Prophecy's sharing model enables teams to reuse project components without compromising governance.
+
+Projects can be shared with other teams to extend access. When a project is shared with your team:
+
+- You can import project components into your own projects through the [Package Hub](/engineers/package-hub).
+- You can run [business applications](/analysts/business-applications) built on top of project pipelines.
+- You **cannot** modify original project components.
+
+This model encourages the creation of reusable components that can be leveraged across teams without duplication. When a team creates a high-quality transformation or dataset definition, other teams can incorporate it into their workflows without risk of breaking the original implementation.
+
+:::note
+Business applications are only available for SQL projects at this time.
+:::
+
+## Project and fabric relationships
+
+The relationship between projects and fabrics is a fundamental aspect of Prophecy's architecture that directly impacts your team-based access strategy. Let's see how these elements interact.
+
+### Execution requirements
+
+Prophecy projects must be connected to a fabric to run pipelines. This is because fabrics contain your connections to execution environments and data sources that power your pipelines. Without this connection, a project remains a blueprint that cannot be executed.
+
+### Cross-team connections
+
+A key aspect of this relationship is that project and fabric team assignments operate independently. You can connect a project assigned to one team to a fabric assigned to a different team, provided you are a member of both teams. This independence lets you perform actions such as promoting projects from development to production environments.
+
+For example, a business analyst in the development team can develop and test a project using a development fabric. When ready for production, a platform engineer in both the development team and production team can attach a production fabric to the project.
+
+![Attach different fabrics to a project](img/project-fabric-attachment.png)
+
+:::info
+To accomplish the scenario above, you must ensure that at least one user is a member of both the project's team and the target fabric's team. This way, someone will be able to publish or deploy a project to production environments.
+:::
+
+### Provider compatibility
+
+While cross-team connections provide flexibility, there are technical constraints to consider. For SQL projects **only**, the project must have the same provider as the fabric. This means:
+
+- Databricks projects can only attach to Databricks fabrics.
+- Snowflake projects can only connect to Snowflake fabrics.
+
+:::note
+Python and Scala projects do not specify "providers" at creation. These projects can connect to any Spark fabric.
+:::
diff --git a/sidebars.js b/sidebars.js
index 5871e79f9f2..9103c68f291 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -748,6 +748,7 @@ const sidebars = {
       },
       items: [
         "administration/teams-users/settings",
+        "administration/teams-users/team-based-access",
         "administration/teams-users/project-creation-template",
       ],
     },


Reviews:
user: login: atbida
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-25T19:27:41Z
user: login: atbida
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-25T19:32:30Z
user: login: atbida
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-25T19:43:04Z
user: login: atbida
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-25T19:46:09Z
user: login: kathweinschenkprophecy
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-28T15:25:01Z

Review comments:
diff_hunk: @@ -0,0 +1,151 @@
+---
+title: Team-based access
+id: team-based-access
+description: Manage access by team
+tags: []
+---
+
+In Prophecy, access control operates through team associations with resources. Projects and fabrics are the fundamental resources to which teams are assigned. Users who belong to a team can access all projects and fabrics assigned to that team.
+
+This guide provides comprehensive best practices for implementing and managing team-based access to optimize collaboration while maintaining appropriate security boundaries.
+
+:::note
+Team admins have special privileges for managing team membership, but the core access model remains focused on the team-to-resource relationship. Each team can be assigned to many projects and fabrics, but importantly, each project and fabric can only be assigned to one team.
+:::
path: docs/administration/teams-users/team-based-access.md
user: login: atbida
body: I would add a small diagram here with only three boxes: teams, fabrics, and projects. 
created_at: 2025-04-25T19:27:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,151 @@
+---
+title: Team-based access
+id: team-based-access
+description: Manage access by team
+tags: []
+---
+
+In Prophecy, access control operates through team associations with resources. Projects and fabrics are the fundamental resources to which teams are assigned. Users who belong to a team can access all projects and fabrics assigned to that team.
+
+This guide provides comprehensive best practices for implementing and managing team-based access to optimize collaboration while maintaining appropriate security boundaries.
+
+:::note
+Team admins have special privileges for managing team membership, but the core access model remains focused on the team-to-resource relationship. Each team can be assigned to many projects and fabrics, but importantly, each project and fabric can only be assigned to one team.
+:::
+
+## Team structure
+
+The way you structure your teams will fundamentally shape how users interact with data and resources in Prophecy. There are several approaches to team organization, each with its own advantages depending on your organization's needs.
+
+In any case, teams should be assigned only to the resources they genuinely need to access. This principle minimizes the potential impact of compromised credentials and reduces the risk of accidental data modifications.
+
+### Strategy 1: Environment-based teams
+
path: docs/administration/teams-users/team-based-access.md
user: login: atbida
body: these two strategies are really nice!
created_at: 2025-04-25T19:32:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,151 @@
+---
+title: Team-based access
+id: team-based-access
+description: Manage access by team
+tags: []
+---
+
+In Prophecy, access control operates through team associations with resources. Projects and fabrics are the fundamental resources to which teams are assigned. Users who belong to a team can access all projects and fabrics assigned to that team.
+
+This guide provides comprehensive best practices for implementing and managing team-based access to optimize collaboration while maintaining appropriate security boundaries.
+
+:::note
+Team admins have special privileges for managing team membership, but the core access model remains focused on the team-to-resource relationship. Each team can be assigned to many projects and fabrics, but importantly, each project and fabric can only be assigned to one team.
+:::
+
+## Team structure
+
+The way you structure your teams will fundamentally shape how users interact with data and resources in Prophecy. There are several approaches to team organization, each with its own advantages depending on your organization's needs.
+
+In any case, teams should be assigned only to the resources they genuinely need to access. This principle minimizes the potential impact of compromised credentials and reduces the risk of accidental data modifications.
+
+### Strategy 1: Environment-based teams
+
+One of the most straightforward approaches is to split teams based on access to development and production environments. This creates a clear separation between experimentation and production workloads.
+
+#### Dev Team (All Users)
+
+- Limited access to data
+- Access to development environment(s) only
+- Allows for safe experimentation and testing
+
+#### Prod Team (Platform Team Only)
+
+- Complete access and control to production environment
+- Restricted to users responsible for production operations
+- Ensures controlled deployment to production
+
+### Strategy 2: Function-based teams
+
+As organizations scale, they often benefit from more granular team structures aligned with specific job functions. This approach allows for more precise resource allocation and specialized access patterns tailored to different roles within the data ecosystem. Here we provide one example of function-based teams.
+
+#### Data Engineering Team
+
+- Access to all environments, especially with raw data
+- Design and build data pipelines
+- Manage data quality and optimization
+
+#### Marketing Analytics Team
+
+- Access to environment with web analytics and campaign data
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+#### Product Analytics Team
+
+- Access to environment with user behavior data and product metrics
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+## Fabric creation
+
+Fabrics are the bridge between Prophecy and your execution environment. They encapsulate connection details and access credentials, making them a critical component of your security architecture. Thoughtfully configured fabrics ensure that the right people have the right level of access to your data processing resources.
+
+:::note
+Authentication capabilities vary between different connection types across fabrics. Visit individual connection documentation to learn about the specific authentication strategies available for that connection.
+:::
+
+### Development fabrics
+
+Development fabrics should be configured to facilitate collaborative work and allow for experimentation.
+
+- **Team assignment**: Dev team
+- **Connection authentication**: Individual authentication
+- **Benefits**: Maintains accountability with each run linked to an individual identity
+- **Usage**: For projects in development phase only
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for development.
+
+![Development fabric](img/fabric-dev.png)
+
+### Production fabrics
+
+Production fabrics require a different approach focused on stability and reliability. These environments run your business-critical processes and must operate consistently without frequent intervention.
+
+- **Team assignment**: Prod team
+- **Authentication**: Service principal
+- **Benefits**: Eliminates reauthentication needs and ensures smooth job execution
+- **Usage**: For scheduled pipelines in deployed projects
+
+Using service principals for production fabrics ensures that scheduled jobs continue to run even when individual team members are unavailable or their credentials change.
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for production.
+
+![Production fabric](img/fabric-prod.png)
+
+## Project management
+
+Projects in Prophecy encapsulate data pipelines, gems, tables, and other components. How you structure and assign these projects to teams will differ between use cases.
+
+When you first begin using Prophecy, you can create projects with personal team for experimentation, then migrate to collaborative projects organized by business objectives:
+
+- **Create purpose-specific projects**: "Marketing Analytics," "Customer Retention," etc.
+- **Align with team structure**: Ensure projects are assigned to appropriate teams
+- **Document project scope**: Define project boundaries and ownership
+
+Purpose-specific projects help maintain focus and prevent the sprawl of unrelated components within a single project. By clearly defining each project's boundaries, teams can more easily understand what belongs where and how different components relate to business objectives.
+
+### Sharing and collaboration
+
+Prophecy's sharing model enables teams to reuse project components without compromising governance.
+
+Projects can be shared with other teams to extend access. When a project is shared with your team:
+
+- You can import project components into your own projects through the [Package Hub](/engineers/package-hub).
+- You can run [business applications](/analysts/business-applications) built on top of project pipelines.
+- You **cannot** modify original project components.
+
+This model encourages the creation of reusable components that can be leveraged across teams without duplication. When a team creates a high-quality transformation or dataset definition, other teams can incorporate it into their workflows without risk of breaking the original implementation.
+
+:::note
+Business applications are only available for SQL projects at this time.
+:::
+
+## Project and fabric relationships
+
+The relationship between projects and fabrics is a fundamental aspect of Prophecy's architecture that directly impacts your team-based access strategy. Let's see how these elements interact.
+
+### Execution requirements
+
+Prophecy projects must be connected to a fabric to run pipelines. This is because fabrics contain your connections to execution environments and data sources that power your pipelines. Without this connection, a project remains a blueprint that cannot be executed.
+
+### Cross-team connections
+
+A key aspect of this relationship is that project and fabric team assignments operate independently. You can connect a project assigned to one team to a fabric assigned to a different team, provided you are a member of both teams. This independence lets you perform actions such as promoting projects from development to production environments.
path: docs/administration/teams-users/team-based-access.md
user: login: atbida
body: I suggest adding parenthesis (assigned to one team)
created_at: 2025-04-25T19:43:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,151 @@
+---
+title: Team-based access
+id: team-based-access
+description: Manage access by team
+tags: []
+---
+
+In Prophecy, access control operates through team associations with resources. Projects and fabrics are the fundamental resources to which teams are assigned. Users who belong to a team can access all projects and fabrics assigned to that team.
+
+This guide provides comprehensive best practices for implementing and managing team-based access to optimize collaboration while maintaining appropriate security boundaries.
+
+:::note
+Team admins have special privileges for managing team membership, but the core access model remains focused on the team-to-resource relationship. Each team can be assigned to many projects and fabrics, but importantly, each project and fabric can only be assigned to one team.
+:::
+
+## Team structure
+
+The way you structure your teams will fundamentally shape how users interact with data and resources in Prophecy. There are several approaches to team organization, each with its own advantages depending on your organization's needs.
+
+In any case, teams should be assigned only to the resources they genuinely need to access. This principle minimizes the potential impact of compromised credentials and reduces the risk of accidental data modifications.
+
+### Strategy 1: Environment-based teams
+
+One of the most straightforward approaches is to split teams based on access to development and production environments. This creates a clear separation between experimentation and production workloads.
+
+#### Dev Team (All Users)
+
+- Limited access to data
+- Access to development environment(s) only
+- Allows for safe experimentation and testing
+
+#### Prod Team (Platform Team Only)
+
+- Complete access and control to production environment
+- Restricted to users responsible for production operations
+- Ensures controlled deployment to production
+
+### Strategy 2: Function-based teams
+
+As organizations scale, they often benefit from more granular team structures aligned with specific job functions. This approach allows for more precise resource allocation and specialized access patterns tailored to different roles within the data ecosystem. Here we provide one example of function-based teams.
+
+#### Data Engineering Team
+
+- Access to all environments, especially with raw data
+- Design and build data pipelines
+- Manage data quality and optimization
+
+#### Marketing Analytics Team
+
+- Access to environment with web analytics and campaign data
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+#### Product Analytics Team
+
+- Access to environment with user behavior data and product metrics
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+## Fabric creation
+
+Fabrics are the bridge between Prophecy and your execution environment. They encapsulate connection details and access credentials, making them a critical component of your security architecture. Thoughtfully configured fabrics ensure that the right people have the right level of access to your data processing resources.
+
+:::note
+Authentication capabilities vary between different connection types across fabrics. Visit individual connection documentation to learn about the specific authentication strategies available for that connection.
+:::
+
+### Development fabrics
+
+Development fabrics should be configured to facilitate collaborative work and allow for experimentation.
+
+- **Team assignment**: Dev team
+- **Connection authentication**: Individual authentication
+- **Benefits**: Maintains accountability with each run linked to an individual identity
+- **Usage**: For projects in development phase only
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for development.
+
+![Development fabric](img/fabric-dev.png)
+
+### Production fabrics
+
+Production fabrics require a different approach focused on stability and reliability. These environments run your business-critical processes and must operate consistently without frequent intervention.
+
+- **Team assignment**: Prod team
+- **Authentication**: Service principal
+- **Benefits**: Eliminates reauthentication needs and ensures smooth job execution
+- **Usage**: For scheduled pipelines in deployed projects
+
+Using service principals for production fabrics ensures that scheduled jobs continue to run even when individual team members are unavailable or their credentials change.
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for production.
+
+![Production fabric](img/fabric-prod.png)
+
+## Project management
+
+Projects in Prophecy encapsulate data pipelines, gems, tables, and other components. How you structure and assign these projects to teams will differ between use cases.
+
+When you first begin using Prophecy, you can create projects with personal team for experimentation, then migrate to collaborative projects organized by business objectives:
+
+- **Create purpose-specific projects**: "Marketing Analytics," "Customer Retention," etc.
+- **Align with team structure**: Ensure projects are assigned to appropriate teams
+- **Document project scope**: Define project boundaries and ownership
+
+Purpose-specific projects help maintain focus and prevent the sprawl of unrelated components within a single project. By clearly defining each project's boundaries, teams can more easily understand what belongs where and how different components relate to business objectives.
+
+### Sharing and collaboration
+
+Prophecy's sharing model enables teams to reuse project components without compromising governance.
+
+Projects can be shared with other teams to extend access. When a project is shared with your team:
+
+- You can import project components into your own projects through the [Package Hub](/engineers/package-hub).
+- You can run [business applications](/analysts/business-applications) built on top of project pipelines.
+- You **cannot** modify original project components.
+
+This model encourages the creation of reusable components that can be leveraged across teams without duplication. When a team creates a high-quality transformation or dataset definition, other teams can incorporate it into their workflows without risk of breaking the original implementation.
+
+:::note
+Business applications are only available for SQL projects at this time.
+:::
+
+## Project and fabric relationships
+
+The relationship between projects and fabrics is a fundamental aspect of Prophecy's architecture that directly impacts your team-based access strategy. Let's see how these elements interact.
+
+### Execution requirements
+
+Prophecy projects must be connected to a fabric to run pipelines. This is because fabrics contain your connections to execution environments and data sources that power your pipelines. Without this connection, a project remains a blueprint that cannot be executed.
+
+### Cross-team connections
+
+A key aspect of this relationship is that project and fabric team assignments operate independently. You can connect a project assigned to one team to a fabric assigned to a different team, provided you are a member of both teams. This independence lets you perform actions such as promoting projects from development to production environments.
+
+For example, a data scientist in the development team can develop and test a project using a development fabric. When ready for production, a platform engineer in both the development team and production team can attach a production fabric to the project.
path: docs/administration/teams-users/team-based-access.md
user: login: atbida
body: I would add a picture here showing the steps described above.

created_at: 2025-04-25T19:46:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,151 @@
+---
+title: Team-based access
+id: team-based-access
+description: Manage access by team
+tags: []
+---
+
+In Prophecy, access control operates through team associations with resources. Projects and fabrics are the fundamental resources to which teams are assigned. Users who belong to a team can access all projects and fabrics assigned to that team.
+
+This guide provides comprehensive best practices for implementing and managing team-based access to optimize collaboration while maintaining appropriate security boundaries.
+
+:::note
+Team admins have special privileges for managing team membership, but the core access model remains focused on the team-to-resource relationship. Each team can be assigned to many projects and fabrics, but importantly, each project and fabric can only be assigned to one team.
+:::
+
+## Team structure
+
+The way you structure your teams will fundamentally shape how users interact with data and resources in Prophecy. There are several approaches to team organization, each with its own advantages depending on your organization's needs.
+
+In any case, teams should be assigned only to the resources they genuinely need to access. This principle minimizes the potential impact of compromised credentials and reduces the risk of accidental data modifications.
+
+### Strategy 1: Environment-based teams
+
+One of the most straightforward approaches is to split teams based on access to development and production environments. This creates a clear separation between experimentation and production workloads.
+
+#### Dev Team (All Users)
+
+- Limited access to data
+- Access to development environment(s) only
+- Allows for safe experimentation and testing
+
+#### Prod Team (Platform Team Only)
+
+- Complete access and control to production environment
+- Restricted to users responsible for production operations
+- Ensures controlled deployment to production
+
+### Strategy 2: Function-based teams
+
+As organizations scale, they often benefit from more granular team structures aligned with specific job functions. This approach allows for more precise resource allocation and specialized access patterns tailored to different roles within the data ecosystem. Here we provide one example of function-based teams.
+
+#### Data Engineering Team
+
+- Access to all environments, especially with raw data
+- Design and build data pipelines
+- Manage data quality and optimization
+
+#### Marketing Analytics Team
+
+- Access to environment with web analytics and campaign data
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+#### Product Analytics Team
+
+- Access to environment with user behavior data and product metrics
+- Create reporting pipelines
+- Send reports to BI tools to create dashboards
+- Run business applications
+
+## Fabric creation
+
+Fabrics are the bridge between Prophecy and your execution environment. They encapsulate connection details and access credentials, making them a critical component of your security architecture. Thoughtfully configured fabrics ensure that the right people have the right level of access to your data processing resources.
+
+:::note
+Authentication capabilities vary between different connection types across fabrics. Visit individual connection documentation to learn about the specific authentication strategies available for that connection.
+:::
+
+### Development fabrics
+
+Development fabrics should be configured to facilitate collaborative work and allow for experimentation.
+
+- **Team assignment**: Dev team
+- **Connection authentication**: Individual authentication
+- **Benefits**: Maintains accountability with each run linked to an individual identity
+- **Usage**: For projects in development phase only
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for development.
+
+![Development fabric](img/fabric-dev.png)
+
+### Production fabrics
+
+Production fabrics require a different approach focused on stability and reliability. These environments run your business-critical processes and must operate consistently without frequent intervention.
+
+- **Team assignment**: Prod team
+- **Authentication**: Service principal
+- **Benefits**: Eliminates reauthentication needs and ensures smooth job execution
+- **Usage**: For scheduled pipelines in deployed projects
+
+Using service principals for production fabrics ensures that scheduled jobs continue to run even when individual team members are unavailable or their credentials change.
+
+Here is one example of how you may configure a [Prophecy fabric](docs/administration/fabrics/prophecy-fabrics/prophecy-fabrics.md) for production.
+
+![Production fabric](img/fabric-prod.png)
+
+## Project management
+
+Projects in Prophecy encapsulate data pipelines, gems, tables, and other components. How you structure and assign these projects to teams will differ between use cases.
+
+When you first begin using Prophecy, you can create projects with personal team for experimentation, then migrate to collaborative projects organized by business objectives:
+
+- **Create purpose-specific projects**: "Marketing Analytics," "Customer Retention," etc.
+- **Align with team structure**: Ensure projects are assigned to appropriate teams
+- **Document project scope**: Define project boundaries and ownership
+
+Purpose-specific projects help maintain focus and prevent the sprawl of unrelated components within a single project. By clearly defining each project's boundaries, teams can more easily understand what belongs where and how different components relate to business objectives.
+
+### Sharing and collaboration
+
+Prophecy's sharing model enables teams to reuse project components without compromising governance.
+
+Projects can be shared with other teams to extend access. When a project is shared with your team:
+
+- You can import project components into your own projects through the [Package Hub](/engineers/package-hub).
+- You can run [business applications](/analysts/business-applications) built on top of project pipelines.
+- You **cannot** modify original project components.
+
+This model encourages the creation of reusable components that can be leveraged across teams without duplication. When a team creates a high-quality transformation or dataset definition, other teams can incorporate it into their workflows without risk of breaking the original implementation.
+
+:::note
+Business applications are only available for SQL projects at this time.
+:::
+
+## Project and fabric relationships
+
+The relationship between projects and fabrics is a fundamental aspect of Prophecy's architecture that directly impacts your team-based access strategy. Let's see how these elements interact.
+
+### Execution requirements
+
+Prophecy projects must be connected to a fabric to run pipelines. This is because fabrics contain your connections to execution environments and data sources that power your pipelines. Without this connection, a project remains a blueprint that cannot be executed.
+
+### Cross-team connections
+
+A key aspect of this relationship is that project and fabric team assignments operate independently. You can connect a project assigned to one team to a fabric assigned to a different team, provided you are a member of both teams. This independence lets you perform actions such as promoting projects from development to production environments.
+
+For example, a data scientist in the development team can develop and test a project using a development fabric. When ready for production, a platform engineer in both the development team and production team can attach a production fabric to the project.
path: docs/administration/teams-users/team-based-access.md
user: login: kathweinschenkprophecy
body: Agreed! Building now...
created_at: 2025-04-28T15:25:01Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-04-25T16:08:54Z
body: 🚀 Staging preview available: [https://SimpleDataLabsInc.github.io/prophecy-docs-staging/preview/pr-626/](https://SimpleDataLabsInc.github.io/prophecy-docs-staging/preview/pr-626/)
author_association: NONE
user: login: github-actions[bot]
created_at: 2025-04-28T17:11:38Z
body: 🚀 Staging preview available: [https://SimpleDataLabsInc.github.io/prophecy-docs-staging/preview/pr-626/](https://SimpleDataLabsInc.github.io/prophecy-docs-staging/preview/pr-626/)
author_association: NONE
user: login: github-actions[bot]
created_at: 2025-04-28T17:12:36Z
body: 🚀 Staging preview available: [https://SimpleDataLabsInc.github.io/prophecy-docs-staging/preview/pr-626/](https://SimpleDataLabsInc.github.io/prophecy-docs-staging/preview/pr-626/)
author_association: NONE
user: login: github-actions[bot]
created_at: 2025-04-28T17:14:28Z
body: :mag_right::speech_balloon: [Inkeep](https://inkeep.com) AI search and chat service is syncing content for source 'Prophecy Docs'
author_association: NONE