> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# get_role

> Return a single role with its granted permissions in plain language and the resources shared to it, so you can explain what a user may see and do — and why.

Return a single role with the permissions behind it, in plain language.

This is how you explain what someone can and cannot do, and why: reach for it
when a user does not see something they expect, or to answer who is allowed to
perform an action. Feed it the `id` from any user row's `role` (list\_users,
get\_user, get\_identity), or from list\_roles.

The permissions are rendered as *grants*, not as the raw matrix — a category
the role is denied is left out, and inside an allowed one a yes-or-no
permission the role does not hold is left out too. An absence is therefore
meaningful: a category missing from the result is one the role cannot reach,
which is often the answer to "why can't this user see X". The org-chart `scope`
on statements, requests and commission letters is what decides *whose* records
the role sees, independently of those grants.

`shared_resources` is the other half of the picture: resources shared with the
role individually, which reach past its category permissions. A role denied a
whole category can still read specific resources through a share, so read the
two together. Sharing is a live-environment concept, so those are the live
ones.

<Info>
  This tool needs the company-settings *roles* permission (READ on the Role
  company setting).
</Info>

## Parameters

<Accordion title="Body" defaultOpen>
  <ParamField body="role_id" type="string" required>
    Id of the role to look up — the id list\_roles returns, or the one on the
    `role` of any user row.
  </ParamField>
</Accordion>

## Response

<Accordion title="Body" defaultOpen>
  <ResponseField name="id" type="string" />

  <ResponseField name="resource_url" type="string">
    Deep link to open this role in the Qobra web app.
  </ResponseField>

  <ResponseField name="name" type="string" />

  <ResponseField name="description" type="string" />

  <ResponseField name="default" type="boolean">
    Whether this is the role newly-created users get unless another one is
    picked. Exactly one role of a company is the default.
  </ResponseField>

  <ResponseField name="admin" type="boolean">
    Whether this is the company's built-in Admin role, which holds every
    permission and cannot be edited.
  </ResponseField>

  <ResponseField name="users_count" type="integer">
    Number of non-archived users currently holding this role.
  </ResponseField>

  <ResponseField name="permissions" type="object[]">
    The role's permissions, one entry per category it is allowed at all. A
    denied category is omitted entirely, so a category absent from this list is
    one the role cannot reach — that absence is the answer to "why can't this
    user see X".

    <Expandable title="object properties">
      <ResponseField name="category" type="string">
        Coded permission category — one section of the role's matrix, matching a
        section of the Qobra app. One of: `statement`, `request`, `report`,
        `commission_letter`, `plan`, `quota`, `user`, `data_table`,
        `company_setting`, `audit_trail`, `sandbox`.
      </ResponseField>

      <ResponseField name="name" type="string">
        The category's label as it reads in the web app.
      </ResponseField>

      <ResponseField name="scope" type="string">
        How far the category reaches across the org chart, for the categories
        that have such a setting (statements, requests, commission letters):
        `all` every user's, `users_below` the holder's own plus their reports',
        `me` their own only, `no_access` none at all — the category page opens
        but shows nothing. Null for a category with no org-chart scope. One of:
        `all`, `users_below`, `me`, `no_access`.
      </ResponseField>

      <ResponseField name="permissions" type="object[]">
        What the role is granted inside this category. Only grants are listed:
        a yes-or-no permission the role does not hold is absent, so an empty
        list on a category that has sub-permissions means access to the page
        and nothing more. The request category has no sub-permissions at all —
        its scope is the whole grant.

        <Expandable title="object properties">
          <ResponseField name="permission" type="string">
            Coded sub-permission. A value repeats across categories with a
            different meaning (`role` is the Roles settings page under
            `company_setting`, a user's assigned role under `user`), so read it
            together with the category it sits in.
          </ResponseField>

          <ResponseField name="name" type="string">
            The sub-permission's label as it reads in the web app's role
            settings.
          </ResponseField>

          <ResponseField name="level" type="string">
            How far the granted permission goes. `view` (read), `edit` (write),
            `full` (write plus delete). One of: `view`, `edit`, `full`.
          </ResponseField>

          <ResponseField name="grant" type="string">
            What the role may do, in the web app's own wording — 'Can view' /
            'Can edit' / 'Can edit and delete' for a graded permission, an
            action phrase such as 'Can lock' for a yes-or-no one.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="shared_resources" type="object[]">
    Resources shared with this role individually, on top of what `permissions`
    grants by category. This is the other half of the answer to 'why can this
    user see X': a role denied a category can still reach specific resources
    through a share. Empty when nothing is shared with the role. Live
    environment only.

    <Expandable title="object properties">
      <ResponseField name="resource" type="object">
        The shared resource itself — a saved view, or the report or dashboard
        that was shared.

        <Expandable title="object properties">
          <ResponseField name="id" type="string" />

          <ResponseField name="name" type="string" />
        </Expandable>
      </ResponseField>

      <ResponseField name="resource_type" type="string">
        What kind of resource is shared: `statement`, `request`, `quota` or
        `data_table` for a saved view of that resource, `report` or `dashboard`
        for the object itself.
      </ResponseField>

      <ResponseField name="parent_name" type="string">
        The resource the view filters, when it belongs to one — the data table
        or quota it is a view of. Null for a resource that stands alone.
      </ResponseField>

      <ResponseField name="access" type="string">
        The level this share grants the role on this resource specifically —
        `read` (view it), `write` (edit and re-share it) or `delete` (also
        remove it), each level including the ones before it. One of: `read`,
        `write`, `delete`.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Accordion>