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

Available Roles

Query available roles for a specific resource based on user permissions.

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

When managing user roles and permissions, you need to know which roles are available for assignment to users in a specific resource (organization, pipe, table, or interface). The availableRoles query returns the roles that the current user can assign to other users based on their own permissions and the resource's configuration.

Prerequisites

  1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
  2. Resource Access: Ensure your token has access to the resource you're querying.
  3. Resource UUID: The UUID of the organization, pipe, table or interface you want to query.
  4. Resource Type: The type of resource (organization, repo, or interface).

Step 1: Find Your Resource ID

For Organizations

For Pipes/Tables

  • Open the Pipe or Table in your browser.
  • The URL will include the resource ID: https://app.pipefy.com/pipes/456.
  • Resource ID = 456 (the string after /pipes/ or /databases/).

For Interfaces

Step 2: Get the Resource UUID

Important: The IDs from the URLs for Organizations and Pipes/Tables are not the UUIDs needed for the availableRoles query. You need to query the GraphQL API to get the actual UUIDs.

  • URL IDs: Simple numbers/strings like 123456789 or 456 or ZtEdWh
  • UUIDs: Full UUID format like a1b2c3d4-e5f6-7890-abcd-ef1234567890

The availableRoles query requires the UUID, not the ID from the URL.

For Organizations

{
  organization(id: 123456789) {
    uuid
    name
  }
}

Example Response:

{
  "data": {
    "organization": {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My Organization"
    }
  }
}

For Pipes

{
  pipe(id: 456) {
    uuid
    name
  }
}

Example Response:

{
  "data": {
    "pipe": {
      "uuid": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
      "name": "My Pipe"
    }
  }
}

For Tables/Databases

{
  table(id: "ZtEdWh") {
    uuid
    name
  }
}

Example Response:

{
  "data": {
    "table": {
      "uuid": "9876543210-fedc-ba98-7654-3210fedcba98",
      "name": "My Table"
    }
  }
}

Step 3: Run the Available Roles Query

Operation

query {
  availableRoles(resourceUuid: "resource_uuid", resourceType: RESOURCE_TYPE)
}

Arguments

  • resourceUuid: The UUID of the resource (organization, pipe, table, or interface) to query (required)
  • resourceType: The type of resource to query (required)
    • organization: For organization-level roles
    • repo: For pipe or table roles
    • interface: For interface roles

Example (realistic values)

{
  "resourceUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resourceType": "organization"
}

Expected response

{
  "data": {
    "availableRoles": [
      "super_admin",
      "admin",
      "normal",
      "company_guest",
      "external_guest"
    ]
  }
}

Available Roles by Resource Type

Organization Roles

For organizations, the available roles depend on the user's permissions and the organization's plan:

Default Organization Roles:

  • super_admin: Full administrative access
  • admin: Administrative access with limited permissions
  • normal: Standard user access
  • company_guest: Limited access for company members
  • external_guest: Limited access for external users

Freemium Organizations:

  • Only admin and super_admin roles are available

Paid Plans (Business, Enterprise, Unlimited):

  • All default roles plus custom roles are available

Pipe Roles

For pipes, the available roles depend on the user's organization role and pipe-specific permissions:

Available Pipe Roles:

  • admin: Full administrative access to the pipe
  • member: Standard member access
  • creator: Can create cards but limited other permissions
  • my_cards_only: Can only see and manage their own cards
  • read_and_comment: Read-only access with comment permissions

Role Assignment Rules:

  • Organization admins/super admins can assign any pipe role
  • Pipe admins can assign any pipe role
  • Pipe members can assign roles except admin
  • Users not in the pipe cannot assign any roles

Table Roles

For tables (databases), the available roles are more limited:

Available Table Roles:

  • admin: Full administrative access to the table
  • member: Standard member access
  • read_and_comment: Read-only access with comment permissions

Role Assignment Rules:

  • Organization admins/super admins can assign any table role
  • Table admins can assign any table role
  • Table members can assign roles except admin
  • Users not in the table cannot assign any roles

Interface Roles

For interfaces, the available roles are:

Available Table Roles:

  • admin: Full administrative access to the interface
  • member: Can view the interface pages, can only update editable fields

Role Assignment Rules:

  • Only Interface admins can assign any interface role
  • Interface members cannot assign any roles
  • Users not in the interface cannot assign any roles

Important Notes

How it works

  • Permission-based: The query returns roles based on the current user's ability to assign roles to others
  • Resource-specific: Different resource types have different available roles
  • Plan-dependent: Freemium organizations have limited role options
  • Hierarchy-aware: Users can only assign roles that are equal to or lower than their own role

Role Hierarchy

The role hierarchy determines which roles a user can assign:

  1. super_admin: Can assign any role
  2. admin: Can assign admin, normal, company_guest, external_guest roles
  3. normal: Can assign normal, company_guest, external_guest roles
  4. company_guest: Can assign company_guest, external_guest roles
  5. external_guest: Can assign external_guest roles

Custom Roles

For paid plans, custom roles are also included in the available roles list. Custom roles follow the same hierarchy rules as default roles.

Error scenarios

1. Resource not found

{
  "errors": [
    {
      "message": "Couldn't find Resource with uuid invalid-uuid",
      "extensions": {
        "code": "RESOURCE_NOT_FOUND"
      }
    }
  ]
}

2. Invalid resource type

{
  "errors": [
    {
      "message": "Invalid resource type",
      "extensions": {
        "code": "INVALID_INPUT"
      }
    }
  ]
}

3. Insufficient permissions

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

Examples by Resource Type

Organization Example

query {
  availableRoles(resourceUuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", resourceType: organization)
}

Response for Enterprise plan:

{
  "data": {
    "availableRoles": [
      "super_admin",
      "admin", 
      "normal",
      "company_guest",
      "external_guest",
      "custom_role_1",
      "custom_role_2"
    ]
  }
}

Response for Freemium plan:

{
  "data": {
    "availableRoles": [
      "admin",
      "super_admin"
    ]
  }
}

Pipe Example

query {
  availableRoles(resourceUuid: "f9e8d7c6-b5a4-3210-9876-543210fedcba", resourceType: repo)
}

Response for pipe admin:

{
  "data": {
    "availableRoles": [
      "admin",
      "member",
      "creator",
      "my_cards_only",
      "read_and_comment"
    ]
  }
}

Response for pipe member:

{
  "data": {
    "availableRoles": [
      "member",
      "creator",
      "my_cards_only",
      "read_and_comment"
    ]
  }
}

Table Example

query {
  availableRoles(resourceUuid: "9876543210-fedc-ba98-7654-3210fedcba98", resourceType: repo)
}

Response for table admin:

{
  "data": {
    "availableRoles": [
      "admin",
      "member",
      "read_and_comment"
    ]
  }
}

Interface Example

query {
  availableRoles(resourceUuid: "9876543210-fedc-ba98-7654-3210fe323edc", resourceType: interface)
}

Response for interface admin:

{
  "data": {
    "availableRoles": [
      "admin",
      "member"
    ]
  }
}

Best Practices

  1. Check permissions first: Always verify the current user has permission to assign roles before attempting to assign them.

  2. Handle empty results: An empty array means the user cannot assign any roles to the resource.

  3. Plan awareness: Consider the organization's plan when displaying available roles to users.

  4. Role hierarchy: Respect the role hierarchy - users should only see roles they can actually assign.

  5. Resource type validation: Ensure you're using the correct resource type for the resource you're querying.

Related Operations