diff --git a/port/action-permissions/refreshActionPermissionsToState.go b/port/action-permissions/refreshActionPermissionsToState.go
index 791c27d7..2fa9cc47 100644
--- a/port/action-permissions/refreshActionPermissionsToState.go
+++ b/port/action-permissions/refreshActionPermissionsToState.go
@@ -1,14 +1,13 @@
 package action_permissions
 
 import (
-	"context"
 	"encoding/json"
 	"github.com/hashicorp/terraform-plugin-framework/types"
 	"github.com/port-labs/terraform-provider-port-labs/internal/cli"
 	"github.com/port-labs/terraform-provider-port-labs/internal/flex"
 )
 
-func refreshActionPermissionsState(ctx context.Context, state *ActionPermissionsModel, a *cli.ActionPermissions, actionId string) error {
+func refreshActionPermissionsState(state *ActionPermissionsModel, a *cli.ActionPermissions, actionId string) error {
 	state.ID = types.StringValue(actionId)
 	state.ActionIdentifier = types.StringValue(actionId)
 	state.BlueprintIdentifier = types.StringNull()
diff --git a/port/action-permissions/resource.go b/port/action-permissions/resource.go
index a6f63ad7..ddee22aa 100644
--- a/port/action-permissions/resource.go
+++ b/port/action-permissions/resource.go
@@ -62,7 +62,7 @@ func (r *ActionPermissionsResource) Read(ctx context.Context, req resource.ReadR
 		return
 	}
 
-	err = refreshActionPermissionsState(ctx, state, a, actionIdentifier)
+	err = refreshActionPermissionsState(state, a, actionIdentifier)
 	if err != nil {
 		resp.Diagnostics.AddError("failed to refresh action permissions state", err.Error())
 		return
diff --git a/port/action-permissions/schema.go b/port/action-permissions/schema.go
index ce6ec905..64be9edf 100644
--- a/port/action-permissions/schema.go
+++ b/port/action-permissions/schema.go
@@ -120,22 +120,22 @@ Docs for the Action Permissions resource can be found [here](https://docs.getpor
 
 ` + "```hcl" + `
 resource "port_action_permissions" "restart_microservice_permissions" {
-  action_identifier = port_action.restart_microservice.identifier
-  permissions = {
-    "execute" : {
-      "roles" : [
-        "Admin"
-      ],
-      "users" : [],
-      "teams" : [],
-      "owned_by_team" : true
-    },
-    "approve" : {
-      "roles" : ["Member", "Admin"],
-      "users" : [],
-      "teams" : []
-    }
-  }
+	action_identifier = port_action.restart_microservice.identifier
+	permissions = {
+		"execute" : {
+			"roles" : [
+				"admin"
+			],
+			"users" : [],
+			"teams" : [],
+			"owned_by_team" : true
+		},
+		"approve" : {
+			"roles" : ["member", "admin"],
+			"users" : [],
+			"teams" : []
+		}
+	}
 }` + "\n```" + `
 
 ## Example Usage with Policy
@@ -193,8 +193,31 @@ resource "port_action_permissions" "restart_microservice_permissions" {
   }
 }` + "\n```" + `
 
-## Disclaimer 
+## Disclaimer
 
 - Action permissions are created by default when creating a new action, this means that you should use this resource when you want to change the default permissions of an action.
 - When deleting an action permissions resource using terraform, the action permissions will not be deleted from Port, as they are required for the action to work, instead, the action permissions will be removed from the terraform state.
-`
+- All the permission lists (roles, users, teams) are managed by Port in a sorted manner, this means that if your ` + "`" + `.tf` + "`" + ` has for example roles defined out of order, your state will be invalid
+    E.g:
+
+    ` + "```hcl" + `
+	resource "port_action_permissions" "restart_microservice_permissions" {
+		action_identifier = port_action.restart_microservice.identifier
+		permissions = {
+			# invalid
+			"execute" : {
+				"roles" : [
+					"member",
+					"admin",
+				],
+				...
+			},
+			# valid
+			"approve" : {
+				"roles" : [
+					"admin",
+					"member",
+				],
+			}
+		}
+	}` + "\n```"