docs: improve rbac and permissions

website/docs/docs/authentication/legacy.md

@@ -487,4 +487,4 @@ You can discriminate between users based on the "identity provider" column in ou
 
 You can't make the username/password login dialog disappear, however only users that have been manually invited by email can login with this option. Inviting users is controlled by the [`user:invite` permission](https://docs.pactflow.io/docs/permissions/#userinvite), which by default is only available to Administrators. You can use this permission to create custom roles as needed to control the desired behaviour.
 
-Note it is wise to retain at least one administrative user who can login with a username and password to address break-glass scenarios (e.g., if your SSO provider is down or misconfigured).
+Note it is wise to retain at least one administrative user who can login with a username and password to address break-glass scenarios (for example, if your SSO provider is down or misconfigured).

website/docs/docs/authentication/main.md

@@ -51,7 +51,7 @@ Once SSO has been enabled, any users on the registered SAML domain _must_ login
 
 Users not attached to the SAML domain that have been invited may login using any form. Inviting users is controlled by the [`user:invite` permission](https://docs.pactflow.io/docs/permissions/#userinvite), which by default is only available to Administrators. 
 
-We recommend at least one administrative user who can login with a username and password to address break-glass scenarios (e.g., if your SSO provider is down or misconfigured).
+We recommend at least one administrative user who can login with a username and password to address break-glass scenarios (for example, if your SSO provider is down or misconfigured).
 
 ### 2. I'm an enterprise customer and need SCIM enabled
 

website/docs/docs/permissions/permissions.md

@@ -4,47 +4,80 @@ title: Permissions
 
 _Eligible plans: Enterprise_
 
-Note that "manage" permissions cover both read and write operations.
+# Overview
 
-## ai:*
+PactFlow uses a structured permission model to define what users can do and where. Most permissions follow the format `resource:action:scope` , where:
+
+- `resource` — the type of data or feature the permission applies to (for example, `contract_data`, `webhook`, `user`)
+- `action` — the operation being performed (for example, `read`, `write`, `manage`, `invite`)
+- `scope` — the level or context the permission applies to, such as:
+  - `team` — restricts the permission to resources owned by teams the user belongs to
+  - `*` — applies globally to all resources of that type
+  - `{uuid}` — scoped to a specific team, used for fine-grained delegation (for example, `team:manage:{uuid}`)
+
+Permissions are grant-only. Broader permissions cannot be narrowed by denial (for example, ai:* cannot exclude ai:generation:code).
+
+> Note: `manage` permissions include both read and write access.
+
+**Example:**  
+`contract_data:manage:team` — allows a user to publish, modify, and view contract data for applications owned by any team they belong to.
+
+While most permissions follow this pattern, there are a few exceptions. Refer to the sections below for a complete list of available permissions, including their effects and any additional constraints.
+
+## AI
+
+AI-related permissions are a special case. Instead of applying to data or resources, they control access to AI-powered features within PactFlow.
+
+They are also **hierarchical**, meaning:
+
+- Granting a broader permission (for example, `ai:*`) implies access to all sub-permissions within that namespace.
+- More specific permissions allow access to a narrower feature set.
+
+> **Note:** AI permissions do not include a `scope`, because they do not act on specific team-owned resources. Access is granted globally based on role assignment.
+
+### ai:*
 Provides access to all AI-related features, including all future permissions created under the `ai:` scope.
 
-## ai:generation:*
+### ai:generation:*
 Can generate Pact tests from all current and future supported inputs.
 
-## ai:generation:openapi
+### ai:generation:openapi
 Can generate Pact tests based on user-provided OpenAPI descriptions.
 
-## ai:generation:code
+### ai:generation:code
 Can generate Pact tests based on user-provided client code.
 
-## ai:generation:request-response
+### ai:generation:request-response
 Can generate Pact tests based on recorded request-response pairs.
 
-# ai:generation:test-template
+### ai:generation:test-template
 Can customize generated Pact test output using a predefined example as a template.
 
-## authentication_settings:manage
+## Authentication
+
+### authentication_settings:manage
 
 Manage authentication settings, such as configuring SSO via Github or Google.
 
-## contract_data:bulk_delete:*
+## Application Data
+
+### contract_data:bulk_delete:*
 
 Bulk deletes pacts (which just removes the pacts and their associated verifications), applications (which removes associated pacts, verification results, application versions and webhooks) or an integration (which removes all pacts, verification results and webhooks, but leaves any application referenced by another integration).
 
-## contract_data:bulk_delete:team
+### contract_data:bulk_delete:team
 
 Bulk deletes pacts (see above) where the consumer is assigned to the user's teams.
 
-## contract_data:bulk_delete:own
+### contract_data:bulk_delete:own
 
 Bulk deletes pacts (see above) where the consumer was created by the logged in user.
 
-## contract_data:manage:*
+### contract_data:manage:*
 
 Create, update, and delete any contract related data. This includes applications, application labels, application versions, branches, tags, pacts, and verification results. It allows the user to delete a single pact, but it does not allow to perform bulk deletions. When deleting an application that has associated pacts and versions, you must also have the appropriate bulk delete permission (see also [contract_data:bulk_delete:\*](#contract_data-bulk_delete)).
 
-## contract_data:manage:team
+### contract_data:manage:team
 
 Create, update, and delete contract related data for applications assigned to the user's teams. Pacts are managed by the consumer's team(s) and verification results are managed by the provider's team(s). 
 
@@ -54,114 +87,126 @@ Some PactFlow resources, such as secrets and webhooks, have a team assigned at t
 
 :::
 
-## contract_data:manage:own
+### contract_data:manage:own
 
 Create, update, and delete contract related data for applications created by the logged in user. This permission is required to create an application in PactFlow before it is assigned to a team.
 
-## contract_data:read:*
+### contract_data:read:*
 
 View any contract-related data. This includes applications, application labels, application versions, branches, tags, pacts, and verification results.
 
-## deployment_and_release:record:*
+## Environment and Deployment
+
+### deployment_and_release:record:*
 
 Notify PactFlow that a particular version of an application has been deployed or released. 
 
-## deployment_and_release:record:team
+### deployment_and_release:record:team
 
 Notify PactFlow that a particular version of an application associated with your team has been deployed or released. 
 
-## environment:manage:*
+### environment:manage:*
 
 Create, update, and delete any environment. When creating a new environment, the user can associate it with any team.
 
-## environment:read:*
+### environment:read:*
 
 View a list of all environments.
 
-## environment:read:team
+### environment:read:team
 
 View a list of environments associated with the user's teams.
 
-## read_token:manage:own
+## Tokens
+
+### read_token:manage:own
 
 Manage own *read only* API token. This permission is for users/system accounts that are not allowed to modify any resources (for example, those with the [Viewer](./predefined-roles#viewer) role), for whom it does not make sense to have a read/write token.
 
-## role:manage:*
+## Roles
+
+### role:manage:*
 
 Create, update and delete roles (note that the pre-defined roles cannot be deleted).
 
-## role:read:*
+### role:read:*
 
 View all roles.
 
-## secret:manage:*
+## Secrets
+
+### secret:manage:*
 
 Create, update and delete all secrets.
 
-## secret:manage:team
+### secret:manage:team
 
 Create, update and delete secrets assigned to teams of which the user is a member.
 
-## secret:read:team
+### secret:read:team
 
 View the names and descriptions of secrets assigned to teams of which the user is a member.
 
-## system_account:manage:*
+## Users, System Accounts and Teams
+
+### system_account:manage:*
 
 Create, update, and disable any system account and associated API tokens.
 
-## system_account:manage:team
+### system_account:manage:team
 
 View details, disable, and copy and regenerate API tokens for system accounts assigned to the teams of which the user is a member. Does not currently allow system account creation, but this is expected to be supported in the future.
 
-## system_account:read:*
+### system_account:read:*
 
 View all system accounts (does not allow viewing/copying API tokens).
 
-## system_account:read:team
+### system_account:read:team
 
 View system accounts assigned to the teams of which the user is a member (does not allow viewing/copying API tokens).
 
-## system_preference:manage:*
+### system_preference:manage:*
 
 Manage the global system settings such as API token expiration and application notices.
 
-## team:manage:*
+### team:manage:*
 
 Create, update and delete teams. Add and remove users, environments and applications to/from teams.
 
-## team:manage:{uuid}
+### team:manage:{uuid}
 
 Manage administrators, users, environments and applications associated with a particular team. This permission is only associated with the [Team Administator](./predefined-roles#team-administrator) role and cannot be assigned to any other roles.
 
-## team:read:*
+### team:read:*
 
 View teams and their associated users and applications.
 
-## token:manage:own
+### token:manage:own
 
 Manage own read/write and read only API tokens.
 
-## user:invite
+### user:invite
 
 Invite a user to the PactFlow application.
 
-## user:manage:*
+### user:manage:*
 
 Create, update, and disable any regular user (not system accounts), and modify their roles.
 
-## user:manage_scim_attributes:*
+### user:manage_scim_attributes:*
 
 Set and update the user attributes used by the PactFlow SCIM API to identify the user in the external Identity Provider (`externalIdpUsername` and `externalIdpId`). Must be used in conjuction with `user:invite` and `user:manage` permissions. This permission can only be associated with the SCIM role.
 
-## user:read:*
+### user:read:*
 
 View all regular users (not system accounts) and their associated roles.
 
-## webhook:manage:*
+## Webhooks
+
+### webhook:manage:*
 
 Create, update, and delete any webhook.
 
-## webhook:manage:team
+### webhook:manage:team
 
 Create, update and delete webhooks assigned to the teams of which the user is a member.

website/docs/docs/permissions/rbac.md

@@ -0,0 +1,100 @@
+---
+title: Role-Based Access Control
+sidebar_label: Overview
+description: Learn how PactFlow manages access through users, teams, roles, and permissions.
+---
+
+# Role-Based Access Control
+
+PactFlow uses a flexible team-based Role-Based Access Control (RBAC) model to manage access to contracts, applications, and features. This ensures users can only interact with resources in ways allowed by their assigned roles and team membership.
+
+This model supports simple team structures and scales to complex organizations.
+
+## Core concepts
+
+- **Users**: Individuals who interact with PactFlow via the UI, API, or CLI.
+- **Roles**: Global collections of permissions assigned to users.
+- **Permissions**: Actions a user can perform. Some may be scoped to specific teams or resources.
+- **Teams**: Logical groups of users that own applications and resources.
+- **Applications**: Team-owned services that participate in contract testing.
+- **Contracts**: The data generated from interactions between applications.
+- **Resources**: Include secrets, webhooks, test results, and other team-scoped assets.
+
+## How it works
+
+PactFlow uses a flexible RBAC model where:
+
+- **Users are assigned one or more global roles**
+- **Roles grant a set of permissions**
+- **Some permissions are scoped to specific teams or resources**
+
+While roles are assigned globally to a user, many permissions are evaluated in context — particularly when scoped to a team.
+
+For example:
+
+- A user with the `contract_data:manage:team` permission can modify contract data **only** for applications owned by teams they belong to.
+- A user with `user:invite` (no scope) can invite users across the entire organization.
+
+A user's **effective permissions** are therefore a combination of:
+
+* Their globally assigned roles
+* The permissions granted by those roles
+* The team or resource scope (if applicable) of those permissions
+* The teams they are a member of (when a permission is team-scoped)
+
+### Special case: Team Administrator
+
+The **Team Administrator** is a special permission-based role assigned to a user _for a specific team_. It is implemented using a scoped permission like:
+
+```
+team:manage:{team_uuid}
+```
+
+This allows for delegated administration of a team without giving the user global administrative rights.
+
+> **Note:** Roles are additive — there are no negated permissions in PactFlow.
+
+### Conceptual Model
+
+![Diagram](/img/rbac.png)
+
+## Example: Team-based access
+
+This guide walks you through an example with two teams, three applications, and three users, one of whom is a platform administrator.
+
+### Team structure
+
+| **Team** | **Applications** | **Users** |
+|----------|------------------|-----------|
+| A        | ProductService, OrderService         | Sally     |
+| B        | OrderService, AuthService         | Billy     |
+
+### User access and roles
+
+| **User** | **Team** | **Role**          | **Access Rights** |
+|----------|----------|-------------------|-------------------|
+| Sally    | A        | Test Maintainer   | ProductService, OrderService          |
+| Billy    | B        | Test Maintainer   | OrderService, AuthService          |
+| Kevin    | -        | Administrator     | All               |
+
+- Sally and Billy can only act on applications owned by their assigned teams.
+- Kevin, as an Administrator, can access and manage any application or contract in the system.
+
+If Sally attempts to publish a contract for an application not owned by her team (for example, `AuthService`), she will receive a permissions error.
+
+Example error:
+
+```
+Failed to tag versions due to error: PactBroker::Client::Error – Authorization failed (403)
+One or more pacts failed to be published
+```
+
+This demonstrates how access is enforced based on both ownership and role-based permissions.
+
+> **Note:** See [Predefined Roles](/docs/permissions/predefined-roles) for more details on role capabilities.
+
+
+## More Information
+
+* For a list of the default roles, visit the [Roles Overview](/docs/permissions/predefined-roles).
+* For a list of supported permissions, visit the [Permissions Overview](/docs/permissions).

website/docs/docs/troubleshooting/apihub.md

@@ -99,7 +99,7 @@ https://app.pactflow.io
   - Directed to their default tenant, or
   - Presented with a list of organisations they belong to.
 
-> Your existing tenant-specific URL (e.g., `xyz.pactflow.io`) will continue to work.
+> Your existing tenant-specific URL (for example, `xyz.pactflow.io`) will continue to work.
 
 ### Website and Marketing Collateral
 

website/sidebars.js

@@ -78,6 +78,7 @@ module.exports = {
           type: "category",
           label: "Roles and permissions",
           items: [
+            "docs/permissions/rbac",
             "docs/permissions/predefined-roles",
             "docs/permissions/permissions",
             "docs/permissions/api-tokens",