Create Custom Role

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

Teams may need customized permissions, so custom roles allow to more granular access control.

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 will be created.

4. Plan: Custom Roles are only available for Business, Enterprise and Unlimited plans.

Step 1: Find Your Organization ID

1. Via Pipefy UI

• Open the Organization in your browser.
• The URL will include the Organization ID: https://app.pipefy.com/organizations/123456789.
• Organization ID = 123456789 (the number after /organizations/).

2. Run the mutation

Operation

mutation {
  createCustomRole(input: {
    orgId: "id",
    title: "Billing Management",
    description: "Will have access to billing information",
    referenceRole: "admin"
  }) {
    success
    role{
      created_by
      description
      id
      isCustom
      memberCount
      name
      title
      updated_by
      uuid
    }
  }
}

Arguments (input)

• orgId: Organization ID
• title: Title of the custom role. Max 20 characters.
• description: Description for the custom role. Max 140 characters.
• referenceRole: The role name to copy the default permissions. Options:
  • start_from_scratch: No permission is going to be selected for the new role
  • super_admin: The permissions selected are going to be the same as the super_admin role
  • admin: The permissions selected are going to be the same as the admin role
  • normal: The permissions selected are going to be the same as the normal role
  • company_guest: The permissions selected are going to be the same as the company_guest role
  • external_guest: The permissions selected are going to be the same as the external_guest role

Example (realistic values)

{
  "input": {
    "orgId": "980700673",
    "title": "Billing Management",
    "description": "Will have access to billing information",
    "referenceRole": "admin"
  }
}

Expected response

{
  "data": {
    "createCustomRole": {
      "success": true,
      "role": {
        "created_by": "45093a33-cfb3-4d49-9c7f-17b623a577c3",
        "description": "Will have access to billing information",
        "id": "149",
        "isCustom": true,
        "memberCount": 0,
        "name": "billing_management",
        "title": "Billing Management",
        "updated_by": null,
        "uuid": "6aae2f14-2ea7-4e76-a9a5-2576375bf349"
      }
    }
  }
}