API Reference
Support from Community ↗︎Back to Pipefy ↗︎

Save Role Permission

Update permissions for a custom role in an organization.

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Why this use case

After creating a custom role, you may need to modify its permissions to better fit your organization's needs. The SaveRolePermission mutation allows you to update the permissions assigned to a custom role by specifying which permissions should be granted.

Prerequisites

  1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
  2. Permissions: Ensure your token has the Super Admin Role.
  3. Organization ID: Identify the Organization where the Custom Role exists.
  4. Plan: Custom Roles are only available for Business, Enterprise and Unlimited plans.
  5. Role ID: The ID of the custom role you want to update.
  6. Permission IDs: The IDs of the permissions you want to assign to the role.

Step 1: Find Your Organization ID

1. Via Pipefy UI

Step 2: Get the Role ID

You can find the role ID by querying the organization's roles:

query {
  organization(id: "YOUR_ORG_ID") {
    roles {
      id
      name
      title
      isCustom
    }
  }
}

Step 3: Get Available Permissions

To see what permissions are available for a role and which ones are currently selected, use the following query:

query {
  permissionsByRoleId(roleId: "ROLE_ID") {
    role {
      id
      name
      title
      isCustom
    }
    permissions {
      id
      name
      selected
      resourceType
      enabled
    }
    permissionSession {
      name
      permissions {
        id
        name
        resourceType
        selected
        enabled
      }
    }
  }
}

This query will return:

  • role: Information about the role
  • permissions: A flat list of all available permissions with their IDs, names, and current selection status
  • permissionSession: Permissions grouped by features (e.g., Admin Panel, Pipes, Databases, etc.)

Step 4: Run the mutation

Operation

mutation {
  saveRolePermission(
    roleId: "role_id"
    permissionIds: ["permission_id_1", "permission_id_2", "permission_id_3"]
  ) {
    success
  }
}

Arguments

  • roleId: The ID of the role to update permissions for (required)
  • permissionIds: Array of permission IDs to assign to the role (optional, defaults to empty array)

Example (realistic values)

{
  "roleId": "149",
  "permissionIds": ["1", "5", "12", "23", "45"]
}

Expected response

{
  "data": {
    "saveRolePermission": {
      "success": true
    }
  }
}

Important Notes

How it works

  • Replaces all permissions: The mutation replaces ALL current permissions for the role with the ones specified in permissionIds
  • Empty array removes all: Passing an empty array [] will remove all permissions from the role
  • Only editable permissions: Only permissions that are marked as "editable" for the role can be assigned

Role restrictions

  • Super Admin only: Only users with Super Admin role can modify role permissions
  • Custom roles: You can modify permissions for custom roles and some default roles
  • Company Guest special rules: For company_guest roles, you can only assign the create_pipe permission or remove all permissions

Permission validation

  • Valid permission IDs: All permission IDs must exist and be valid for the organization
  • Resource type matching: Permissions must match the role's resource type (Organization)
  • Editable permissions only: Only permissions marked as editable for the role can be assigned

Error scenarios

1. Insufficient permissions

{
  "errors": [
    {
      "message": "Permission denied",
      "extensions": {
        "code": "PERMISSION_DENIED"
      }
    }
  ]
}

2. Role not found

{
  "errors": [
    {
      "message": "Couldn't find Role",
      "extensions": {
        "code": "RESOURCE_NOT_FOUND"
      }
    }
  ]
}

3. Invalid permission for company_guest role

{
  "errors": [
    {
      "message": "Permission denied",
      "extensions": {
        "code": "PERMISSION_DENIED"
      }
    }
  ]
}

4. Organization plan doesn't support custom roles

{
  "errors": [
    {
      "message": "Feature not allowed by organization plan",
      "extensions": {
        "code": "FEATURE_NOT_ALLOWED_BY_ORGANIZATION_PLAN"
      }
    }
  ]
}

Related Operations