Assignable 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. Invitation permission: The caller must belong to the organization and have permission to invite members.
3. Organization UUID: The UUID of the organization whose assignable roles you want to list.

Steps

Step 1: Get the organization UUID

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

Step 2: List assignable roles

query {
  assignableRoles(organizationUuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890") {
    name
    uuid
    title
  }
}

The organizationUuid argument is required.

Example response:

{
  "data": {
    "assignableRoles": [
      {
        "name": "normal",
        "uuid": "11111111-1111-1111-1111-111111111111",
        "title": "Company member"
      },
      {
        "name": "company_guest",
        "uuid": "22222222-2222-2222-2222-222222222222",
        "title": "Company Guest"
      },
      {
        "name": "external_guest",
        "uuid": "33333333-3333-3333-3333-333333333333",
        "title": "External Guest"
      }
    ]
  }
}

Key Notes

• The list is filtered by the current user's organization-role hierarchy. A Member (normal) receives normal, company_guest, and external_guest. An Admin also receives admin, and super_admin only when become_super_admin is authorized.
• This field requires invite_user, but does not require show_roles. Invite-only members can load role UUIDs for bulk invite without receiving the full role-management catalog.
• The response is a bounded array (default organization roles only), not a connection.
• A missing organization UUID returns RESOURCE_NOT_FOUND.
• Related: Available Roles returns role names only and is unchanged.