phasehq · rohan-chaturvedi · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
diff --git a/public/access-control.md b/public/access-control.md
@@ -90,6 +90,8 @@ The Phase End-to-End encryption implementation works in conjunction with the acc
 
 Global access is a special type of permission that grants users with a "global access" role implicit access to all Apps and Environments across the organization. Currently, Global access is reserved exclusively for the Phase managed `Owner` and `Admin` roles.
 
+Users can only grant permissions that their own role holds. The `Owner` and `Admin` roles are exempt from this limit. [Read more](/access-control/roles) about how roles work.
+
 ### External Auth Method Considerations
 
 - To use an external auth provider for programmatic authentication with Phase to access sensitive data (e.g., Secrets) via the Phase API, SDKs, or the Kubernetes Operator, you must enable Server-side Encryption (SSE) so that Phase can generate a Service Token on the server side with access to given application(s) or environment(s).

diff --git a/public/access-control/roles.md b/public/access-control/roles.md
@@ -21,6 +21,10 @@ To assign a role to a user or change a user's role:
 ![3-click-current-role](/assets/images/console/access-control/roles/switch-user-role/3-switch-user-role.png)
 4. Once selected, you will see a toast notification confirming that the role has been updated.
 
+<Note>
+ You can only assign a role whose permissions your own role also has. The dropdown disables roles with permissions that your role does not have. This limit does not apply to users with the `Owner` or `Admin` role.
+</Note>
+
 ## Managed Roles
 
 Phase provides managed roles out of the box to every organization.
@@ -44,9 +48,11 @@ The organization owner. This role is automatically assigned when a user creates
 | **Roles** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Integration Credentials** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Network Access Policies** | Full access | ✅ | ✅ | ✅ | ✅ |
+| **Logs** | Full access | ✅ |  |  |  |
 | **Teams** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **SCIM** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **SSO** | Full access | ✅ | ✅ | ✅ | ✅ |
+| **Log Streams** | Full access | ✅ | ✅ | ✅ | ✅ |
 
 #### App-level permissions:
 
@@ -84,9 +90,11 @@ Admin users have access to most resources and permissions, and have global acces
 | **Roles** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Integration Credentials** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Network Access Policies** | Full access | ✅ | ✅ | ✅ | ✅ |
+| **Logs** | Full access | ✅ |  |  |  |
 | **Teams** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **SCIM** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **SSO** | Full access | ✅ | ✅ | ✅ | ✅ |
+| **Log Streams** | Full access | ✅ | ✅ | ✅ | ✅ |
 
 #### App-level permissions:
 
@@ -102,7 +110,7 @@ Admin users have access to most resources and permissions, and have global acces
 | **Members** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Service Accounts** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Integrations** | Full access | ✅ | ✅ | ✅ | ✅ |
-| **Encryption Mode** | Custom access | ✅ |  | ✅ |  |
+| **Encryption Mode** | Full access | ✅ |  | ✅ |  |
 | **Teams** | Full access | ✅ | ✅ | ✅ | ✅ |
 
 The `Owner` and `Admin` roles have global access. Learn more about global access [here](/access-control#global-access).
@@ -126,15 +134,17 @@ Management users with broad access to environments, secrets, and service account
 | **Roles** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Integration Credentials** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Network Access Policies** | Full access | ✅ | ✅ | ✅ | ✅ |
+| **Logs** | Full access | ✅ |  |  |  |
 | **Teams** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **SCIM** | No access | ❌ | ❌ | ❌ | ❌ |
 | **SSO** | No access | ❌ | ❌ | ❌ | ❌ |
+| **Log Streams** | No access | ❌ | ❌ | ❌ | ❌ |
 
 #### App-level permissions:
 
 | Resource | Access | Read | Create | Update | Delete |
 |----------|--------|------|--------|--------|--------|
-| **Environments** | Custom access | ✅ | ✅ | ✅ | ❌ |
+| **Environments** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Secrets** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **DynamicSecretLeases** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **RotatingSecrets** | Full access | ✅ | ✅ | ✅ | ✅ |
@@ -144,7 +154,7 @@ Management users with broad access to environments, secrets, and service account
 | **Members** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Service Accounts** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Integrations** | Full access | ✅ | ✅ | ✅ | ✅ |
-| **Encryption Mode** | Custom access | ✅ | ❌ | ✅ | ❌ |
+| **Encryption Mode** | Full access | ✅ |  | ✅ |  |
 | **Teams** | Full access | ✅ | ✅ | ✅ | ✅ |
 
 ### Service
@@ -166,25 +176,27 @@ Default role for Service Accounts, providing programmatic access to secrets with
 | **Roles** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Integration Credentials** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Network Access Policies** | Read access | ✅ | ❌ | ❌ | ❌ |
+| **Logs** | No access | ❌ |  |  |  |
 | **Teams** | No access | ❌ | ❌ | ❌ | ❌ |
 | **SCIM** | No access | ❌ | ❌ | ❌ | ❌ |
 | **SSO** | No access | ❌ | ❌ | ❌ | ❌ |
+| **Log Streams** | No access | ❌ | ❌ | ❌ | ❌ |
 
 #### App-level permissions:
 
 | Resource | Access | Read | Create | Update | Delete |
 |----------|--------|------|--------|--------|--------|
 | **Environments** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Secrets** | Full access | ✅ | ✅ | ✅ | ✅ |
-| **DynamicSecretLeases** | Full access | ✅ | ✅ | ❌ | ❌ |
+| **DynamicSecretLeases** | Custom access | ✅ | ✅ | ❌ | ❌ |
 | **RotatingSecrets** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Lockbox** | No access | ❌ | ❌ | ❌ | ❌ |
 | **Logs** | No access | ❌ | ❌ | ❌ | ❌ |
 | **Tokens (Legacy)** | No access | ❌ | ❌ | ❌ | ❌ |
 | **Members** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Service Accounts** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Integrations** | Read access | ✅ | ❌ | ❌ | ❌ |
-| **Encryption Mode** | Read access | ✅ | ❌ | ❌ | ❌ |
+| **Encryption Mode** | Read access | ✅ |  | ❌ |  |
 | **Teams** | Read access | ✅ | ❌ | ❌ | ❌ |
 
 ### Developer
@@ -206,25 +218,27 @@ Developers have limited permissions at the organization level and must be given
 | **Roles** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Integration Credentials** | Custom access | ✅ | ✅ | ✅ | ❌ |
 | **Network Access Policies** | Read access | ✅ | ❌ | ❌ | ❌ |
+| **Logs** | Full access | ✅ |  |  |  |
 | **Teams** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **SCIM** | No access | ❌ | ❌ | ❌ | ❌ |
 | **SSO** | No access | ❌ | ❌ | ❌ | ❌ |
+| **Log Streams** | No access | ❌ | ❌ | ❌ | ❌ |
 
 #### App-level permissions:
 
 | Resource | Access | Read | Create | Update | Delete |
 |----------|--------|------|--------|--------|--------|
 | **Environments** | Custom access | ✅ | ✅ | ✅ | ❌ |
 | **Secrets** | Full access | ✅ | ✅ | ✅ | ✅ |
-| **DynamicSecretLeases** | Full access | ✅ | ✅ | ❌ | ❌ |
+| **DynamicSecretLeases** | Custom access | ✅ | ✅ | ❌ | ❌ |
 | **RotatingSecrets** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Lockbox** | Full access | ✅ | ✅ | ✅ | ✅ |
 | **Logs** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Tokens (Legacy)** | Custom access | ✅ | ✅ | ❌ | ❌ |
 | **Members** | Read access | ✅ | ❌ | ❌ | ❌ |
 | **Service Accounts** | Custom access | ❌ | ✅ | ❌ | ❌ |
 | **Integrations** | Full access | ✅ | ✅ | ✅ | ✅ |
-| **Encryption Mode** | Custom access | ✅ |  | ✅ |  |
+| **Encryption Mode** | Full access | ✅ |  | ✅ |  |
 | **Teams** | Read access | ✅ | ❌ | ❌ | ❌ |
 
 ## Custom Roles
@@ -241,6 +255,10 @@ In addition to the managed roles, Phase allows you to create custom roles tailor
 Please make sure to follow the [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when setting the access policy for roles. Casting a wider scope may inadvertently lead to [Privilege escalation](https://en.wikipedia.org/wiki/Privilege_escalation). 
 </Warning>
 
+<Note>
+ You can only grant permissions that your own role has. Phase disables the toggles for permissions that your role does not have. This limit does not apply to users with the `Owner` or `Admin` role.
+</Note>
+
 1. Navigate to the Access Control page from the sidebar and click on the Roles tab.
 ![1-navigate-to-access-control](/assets/images/console/access-control/roles/create-custom-roles/1-navigate-to-access-control.png)
 ![2-navigate-to-access-control-roles](/assets/images/console/access-control/roles/create-custom-roles/2-navigate-to-access-control-roles.png)
@@ -308,3 +326,7 @@ Some actions require a combination of permissions across multiple resources. Bel
 3. Modify the role as needed.
 4. Save your changes.
 ![4-save-modified-role](/assets/images/console/access-control/roles/edit-custom-roles/4-save-modified-role.png)
+
+<Note>
+ You can only add permissions that your own role has. If the role already has permissions that your role does not have, you can keep them or remove them, but you cannot add them back. This limit does not apply to users with the `Owner` or `Admin` role.
+</Note>
diff --git a/public/access-control/service-accounts.md b/public/access-control/service-accounts.md
@@ -46,6 +46,10 @@ By default, when you create a new Service Account it uses the [Service](/access-
 
 You may choose to select a different Managed role or a Custom role by clicking one from the dropdown.
 
+<Note>
+ You can only select a role whose permissions your own role also has. The dropdown disables roles with permissions that your role does not have. This limit does not apply to users with the `Owner` or `Admin` role.
+</Note>
+
 ![Create new service account](/assets/images/console/access-control/service-accounts/create-new-service-accounts/4-create-new-service-account.png)
 
 Click "Create service account". This will create a new account with the chosen name and role. 
@@ -73,6 +77,10 @@ To update the name of an account, simply click the account name at the top of th
 
 To update an account's role, click the role label to open the dropdown and select a role from the list. The selected role will be applied on selection.
 
+<Note>
+ You can only select a role whose permissions your own role also has. For a team-owned account, Phase also counts the permissions of the team [role override](/access-control/teams#role-overrides). This limit does not apply to users with the `Owner` or `Admin` role.
+</Note>
+
 ![Update service account role](/assets/images/console/access-control/service-accounts/manage-account/service-account-update-role.png)
 
 ### Delete account

diff --git a/public/access-control/teams.md b/public/access-control/teams.md
@@ -140,6 +140,8 @@ Teams support two optional role overrides that change what permissions members h
 
 When a role override is set, it replaces the org role's `app_permissions` for resources accessed through that team. Org-level permissions are unaffected.
 
+The [limit on the permissions you can grant](/access-control/roles) does not apply to role overrides. When a team member creates or updates a team-owned service account, Phase adds the **Member role** override permissions to that member's own permissions.
+
 ### Union semantics
 
 When a user has multiple access grants to the same app — whether through individual (direct) access, one or more teams, or a combination — Phase takes the **union** of all applicable permissions. If *any* grant permits an action, the user is allowed to perform it.
@@ -164,6 +166,10 @@ Service accounts can be **owned by a team**, meaning their lifecycle and visibil
 
 ### Creating a team-owned service account
 
+<Note>
+  You can only select a role whose permissions your own role also has. If the team has a **Member role** override, Phase adds the permissions of that override to your own permissions for this check. This limit does not apply to users with the `Owner` or `Admin` role.
+</Note>
+
 1. On the team detail page, click **Create Team Service Account** in the Service Accounts section.
 
 2. Enter a name for the account. 

diff --git a/public/console/organisation.md b/public/console/organisation.md
@@ -36,6 +36,8 @@ You can also invite new members to your Organisation. To invite a new member, cl
 
 You are limited to selecting a non Global Access role when inviting a new member. This is because the user has not created an account and associated cryptographic keys. For more information on Global Access roles, see [Roles](/access-control#global-access).
 
+When you invite a member or change a member's role, you can only select a role whose permissions your own role also has. This limit does not apply to users with the Owner or Admin role.
+
 ## Settings
 
 This page shows your account and recovery info related to this Organisation. You can view your current role, preferences and download your account recovery kit from this screen. This page will also show you the current billing status of your Organisation.

diff --git a/public/console/users.md b/public/console/users.md
@@ -94,4 +94,8 @@ You can permanently remove a member from an Organisation from the [Organisation
 
 Users in Phase must be given a role. By default, users are given the managed "Developer" role when they join an Organisation. This role can be changed once they join. 
 
+<Note>
+  When you invite a member or change a member's role, you can only select a role whose permissions your own role also has. This limit does not apply to users with the "Owner" or "Admin" role.
+</Note>
+
 [Learn about how roles work](/access-control/roles).
diff --git a/public/public-api/errors.md b/public/public-api/errors.md
@@ -44,6 +44,8 @@ Here is a list of the different categories of status codes returned by the Proto
 
     This error may also occur due to a [Network Access Policy](/access-control/network#network-access-policies) that restricts access from your IP address. 
     [Read more](https://docs.phase.dev/access-control/network#access-denied-exceptions) about Network Access Policy exceptions.
+
+    When a role holds permissions that the caller's own role does not have, a create or assign request returns this error. Assignment covers members, invites, and service accounts. A request that updates a role returns this error only when the update adds such a permission.
   </Property>
   <Property name="404">
     A 404 status code indicates that the requested resource does not exist, has been deleted, or belongs to a different organisation. The API does not distinguish between these cases to avoid leaking cross-organisation information.

diff --git a/public/public-api/invites.md b/public/public-api/invites.md
@@ -64,6 +64,7 @@ Invites live under the Members resource — all endpoints are namespaced as `/v1
 
     - The role must not have global access (i.e. Owner and Admin roles cannot be invited to).
     - The role must not permit creating service account tokens.
+    - The role must not include permissions that the caller's own role does not have. Otherwise the request returns `403 Forbidden` with `{"error": "You cannot assign the '<role>' role: it includes permissions your own role does not: <permissions>"}`. Callers with a global-access role are exempt.
     - The email is validated against RFC format; whitespace is trimmed and the local + domain parts are lowercased. Invalid emails return `400 Bad Request`.
     - The email must not already belong to an active member or a pending invite. Duplicate invites return `409 Conflict` with `{"error": "An active invite already exists for '<email>'."}`.
 

diff --git a/public/public-api/members.md b/public/public-api/members.md
@@ -175,6 +175,7 @@ To add a new member, send an invite via the [Invites API](/public-api/invites)
 
     - **The Owner's role is immutable via the API.** Any attempt to PUT the Owner's membership returns `403 Forbidden` with `{"error": "The Owner's role cannot be changed via the API. Use the ownership transfer flow."}`. Ownership transfer is a console-only flow.
     - Users cannot update their own role (`403`).
+    - Callers cannot assign a role that includes permissions their own role does not have. The request returns `403 Forbidden` with `{"error": "You cannot assign the '<role>' role: it includes permissions your own role does not: <permissions>"}`. Callers with a global-access role are exempt.
     - User callers cannot update a member who holds a global-access role (e.g. Admin) unless they themselves hold a global-access role (`403`).
     - Service Account callers cannot update any member who holds a global-access role (`403`), nor can they assign a global-access role to any member (`403`).
 

diff --git a/public/public-api/roles.md b/public/public-api/roles.md
@@ -213,6 +213,8 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
     Custom roles are not available on the Free plan. You must be on a Pro or Enterprise plan to create custom roles.
     </Note>
 
+    - The role can only include permissions that the caller's own role has. Otherwise the request returns `403 Forbidden` with `{"error": "You cannot grant permissions your own role does not include: <permissions>"}`. The error lists each extra permission as `<scope>:<resource>:<action>`, for example `permissions:SSO:create`. Callers with a global-access role (Owner or Admin) are exempt.
+
     ### JSON Body
 
     #### Required fields
@@ -333,6 +335,8 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
 
     Update a custom role's name, description, color, and/or permissions. At least one field must be provided. Default roles cannot be modified (`403 Forbidden`).
 
+    - The request can only add permissions that the caller's own role has. Otherwise the request returns `403 Forbidden` with `{"error": "You cannot grant permissions your own role does not include: <permissions>"}`. This limit applies only to the permissions that the request adds. The caller can change `name`, `description`, or `color`, or remove permissions that the caller does not have. Callers with a global-access role (Owner or Admin) are exempt.
+
     ### URL parameters
 
     <Properties>

diff --git a/public/public-api/service-accounts.md b/public/public-api/service-accounts.md
@@ -125,7 +125,7 @@ When fetching a single service account, additional detail fields are included:
         The service account name. Maximum 64 characters.
       </Property>
       <Property name="role_id" type="string">
-        The ID of the role to assign. Must not be a role with global access (e.g. Owner or Admin).
+        The ID of the role to assign. Must not be a role with global access (e.g. Owner or Admin). The role can only include permissions that the caller's own role has. Otherwise the request returns `403 Forbidden` and the error lists each extra permission. For a team-owned service account, the caller's permissions also include the team's `memberRole` override (or `serviceAccountRole` for service account callers). Callers with a global-access role are exempt.
       </Property>
     </Properties>
 
@@ -314,7 +314,7 @@ When fetching a single service account, additional detail fields are included:
         The new name. Maximum 64 characters. HTML tags and ASCII control characters are stripped; whitespace is trimmed.
       </Property>
       <Property name="role_id" type="string">
-        The ID of the new role. Must not be a global-access role — service accounts cannot hold roles with `global_access: true`.
+        The ID of the new role. Must not be a global-access role — service accounts cannot hold roles with `global_access: true`. If the role changes, the new role can only include permissions that the caller's own role has. Otherwise the request returns `403 Forbidden` and the error lists each extra permission. For a team-owned service account, the caller's permissions also include the team's `memberRole` override (or `serviceAccountRole` for service account callers). Callers with a global-access role are exempt.
       </Property>
     </Properties>