Set User Roles via GraphQL Mutation

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.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: Ensure your token has the necessary permissions.
Card ID: Identify the Card where the email will be created.
Pipe ID: Identify the Pipe where the card you'll create the email is located.

Step 1: Find the IDs

Via Pipefy UI:
1. Organization ID:
  1. Open the Organization in your browser.
  2. The URL will include the Organization ID: https://app.pipefy.com/organizations/123456789.
  3. Organization ID = 123456789 (the number after /open-cards/).
2. Pipe ID:
  1. Open the Pipe in your browser.
  2. The URL will include the Pipe ID: https://app.pipefy.com/pipes/987654321.
  3. Pipe ID = 987654321 (the number after /pipes/).
3. Database (Table) ID
  1. Open the Database in your browser.
  2. The URL will include the Table ID: https://app.pipefy.com/apollo_databases/987654321.
  3. Table ID = 987654321 (the number after /apollo_databases/).
4. User ID:
  1. Open your user preferences in your browser
  2. The URL will include the User ID: https://app.pipefy.com/users/987654321.
  3. User ID = 987654321 (the number after /users/).
  4. To get IDs from other users you should query them throught the API.
Via GraphQL Query:

Step 2: Execute the Mutation

Use the setRoles mutation to assign roles to users.

mutation {
  setRoles(input: {
    organization_id: "123456789",  # Use ONE: organization_id, pipe_id, or table_id  
    members: [
      {
        role_name: "admin",
        user_id: "456789123"
      }
    ]
  }) {
    members {
      role_name
    }
    errors
  }
}

Arguments Breakdown

organization_id, pipe_id, or table_id: The context where the role applies. Use only one per mutation.
members: A list of users and their roles. Each entry requires:
- user_id: The ID of the user.
- role_name: The role to assign

Example Response

{
  "data": {
    "setRoles": {
      "members": [
        {
          "role_name": "admin"
        }
      ],
      "errors": []
    }
  }
}

members: Confirms the assigned roles.
errors: Lists issues (e.g., invalid permissions, incorrect IDs).

Valid Roles

Roles depend on the context (organization_id, pipe_id, or table_id):

1. Organization Roles

super_admin: Super Admin - Full access to the company account. Can create custom roles.
admin: Company Admin - Full access to the company account.
normal: Company Member - Can create new pipes and databases. Can view and access all public pipes and databases.
company_guest: Company Guest (No billing) - Can't access pipes or databases, only Portals, Requests, Tasks, and allowed forms. Can become a Member by creating a pipe or being added to one.
external_guest: External Guest (No billing) - Can't access pipes or databases, only Portals, Requests, Tasks, and allowed forms.

2. Pipe Roles

admin: Pipe administrator - Can create cards and access all of the pipe's existing cards to edit/move them. Can access pipe's settings.
member: Pipe member - Can create cards and access all of the pipe's existing cards to edit/move them.
my_cards_only: Restricted view - Can create and edit cards that they created or that were assigned to them. Can't delete cards.
read_and_comment: Read only - Can only view and comment on cards.
creator: Start form only - Only has access to the start form. No pipe access.

3. Database (Table) Roles

admin: Database admin - Can create, edit and delete all existing records in the database. Can access database settings.
member: Database member - Can access the records. Will be able to create, edit and delete records, if authorized in the database settings.
read_and_comment: Read only - Can access the records.