---
title: "getRole"
method: GET
path: "/v1/permissions/roles/{roleId}"
tags: ["Roles"]
---

# getRole

`GET /v1/permissions/roles/{roleId}`

Get role by id

## Path parameters

- `roleId` string, required — Format: <organization_id>:<slug>

## Response `200`

ok

- union
  - UserRole — A standard user role. Must be explicitly assigned to users.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'user_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `operation` 'equals_current_user', required
    - `parent_role` string — Optional parent role that this role inherits from. Must be an `org_role` or `share_role`.
    - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization.
  - OrgRole — A role automatically applied to all users in an organization.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'org_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `operation` 'equals_current_user', required
    - `pricing_tier` string — The pricing tier of the organization this root role is based on
  - ShareRole — A role that can be assigned to users in other organizations for sharing purposes.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'share_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `operation` 'equals_current_user', required
  - PartnerRole — A role that appears in another organization's role list that can be assigned but not modified by the partner organization.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'partner_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `operation` 'equals_current_user', required
    - `partner_org_id` string — Id of an organization
    - `vendor_enforced_user_limit` integer — Maximum number of users that can be assigned this role (vendor-enforced limit, can only be set via internal auth)
    - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization.
  - PortalRole — A role that is applied to end customers and installers using the Portals
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'portal_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `operation` 'equals_current_user', required

---

[API](https://skmtc.net/epilot/apis/permissions-api.md) · [All operations](https://skmtc.net/epilot/apis/permissions-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/permissions-api/versions/fb87972e9d3c/schema)