Choosable Roles

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

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Organization membership: The caller needs the permission to view roles (show_roles). Callers without it receive PERMISSION_DENIED.
3. Organization UUID: The UUID of the organization whose choosable roles you want to list.

Steps

Step 1: Get the organization UUID

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

Step 2: List the choosable roles

query {
  choosableRoles(organizationUuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", first: 50) {
    edges {
      node {
        name
        title
        description
        custom
      }
    }
  }
}

The organizationUuid argument is required. The field is a Relay connection, so first and after paginate it.

Example response:

{
  "data": {
    "choosableRoles": {
      "edges": [
        { "node": { "name": "admin", "title": "Company admin", "description": "Full access to the company account.", "custom": false } },
        { "node": { "name": "normal", "title": "Company member", "description": "Can create new pipes and databases. Can view and access all public pipes and databases.", "custom": false } },
        { "node": { "name": "billing_owner", "title": "Billing owner", "description": "Handles invoices", "custom": true } }
      ]
    }
  }
}

Key Notes

• Default roles come first, in the same order and with the same names that Available Roles returns for the caller. Each has custom: false and a translated title and description.
• Custom roles come after the default roles, ordered by title. Each has custom: true and its own stored title and description (null when none was set).
• Every caller with show_roles receives all of the organization's custom roles.
• Organizations on the free plan receive no custom roles.
• A missing organization UUID returns RESOURCE_NOT_FOUND.
• Related: Available Roles returns role names only and is unchanged.