---
title: "List Roles"
method: GET
path: "/v2/schema/{proj_id}/{env_id}/roles"
tags: ["Roles"]
---

# List Roles

`GET /v2/schema/{proj_id}/{env_id}/roles`

Lists all tenant roles.

## Path parameters

- `proj_id` string, required — Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").
- `env_id` string, required — Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").

## Query parameters

- `include_total_count` boolean — Include total count in response
- `page` integer — Page number of the results to fetch, starting at 1.
- `per_page` integer — The number of results per page (max 100).
- `search` string — Text search for the object name or key

## Response `200`

Successful Response

- union
  - PaginatedResultRoleRead
    - `data` RoleRead[], required — List of Roles
      - `name` string, required — The name of the role
      - `description` string — optional description string explaining what this role represents, or what permissions are granted to it.
      - `permissions` string[] — list of action keys that define what actions this resource role is permitted to do
      - `attributes` object — optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator
      - `extends` string[] — list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.
      - `granted_to` DerivedRoleBlockRead
        - `when` PermitBackendSchemasSchemaDerivedRoleRuleDerivationSettings — Settings for a derived role or a derived role rule
          - `no_direct_roles_on_object` boolean — If true, the derived role or the specific rule will not apply if the resource has any direct role
        - `id` string, uuid, required — The unique id of the derived_role
        - `users_with_role` DerivedRoleRuleRead[] — the rules of the derived role
          - `role_id` string, uuid, required — the role id that needs to exist on the related resource (from the relation)
          - `resource_id` string, uuid, required — the resource id that needs to exist on the related role (from the relation)
          - `relation_id` string, uuid, required — the relation id that needs to exist between the resource and the related resource
          - `role` string, required — the role key that needs to exist on the related resource (from the relation)
          - `on_resource` string, required — the resource key that needs to exist on the related role (from the relation)
          - `linked_by_relation` string, required — the relation key that needs to exist between the resource and the related resource
          - `when` PermitBackendSchemasSchemaDerivedRoleRuleDerivationSettings — Settings for a derived role or a derived role rule
            - `no_direct_roles_on_object` boolean — If true, the derived role or the specific rule will not apply if the resource has any direct role
      - `v1compat_settings` object
      - `v1compat_attributes` object
      - `key` string, required — A URL-friendly name of the role (i.e: slug). You will be able to query later using this key instead of the id (UUID) of the role.
      - `id` string, uuid, required — Unique id of the role
      - `organization_id` string, uuid, required — Unique id of the organization that the role belongs to.
      - `project_id` string, uuid, required — Unique id of the project that the role belongs to.
      - `environment_id` string, uuid, required — Unique id of the environment that the role belongs to.
      - `created_at` string, date-time, required — Date and time when the role was created (ISO_8601 format).
      - `updated_at` string, date-time, required — Date and time when the role was last updated/modified (ISO_8601 format).
    - `total_count` integer, required
    - `page_count` integer
  - RoleRead[]
    - `name` string, required — The name of the role
    - `description` string — optional description string explaining what this role represents, or what permissions are granted to it.
    - `permissions` string[] — list of action keys that define what actions this resource role is permitted to do
    - `attributes` object — optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator
    - `extends` string[] — list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.
    - `granted_to` DerivedRoleBlockRead
      - `when` PermitBackendSchemasSchemaDerivedRoleRuleDerivationSettings — Settings for a derived role or a derived role rule
        - `no_direct_roles_on_object` boolean — If true, the derived role or the specific rule will not apply if the resource has any direct role
      - `id` string, uuid, required — The unique id of the derived_role
      - `users_with_role` DerivedRoleRuleRead[] — the rules of the derived role
        - `role_id` string, uuid, required — the role id that needs to exist on the related resource (from the relation)
        - `resource_id` string, uuid, required — the resource id that needs to exist on the related role (from the relation)
        - `relation_id` string, uuid, required — the relation id that needs to exist between the resource and the related resource
        - `role` string, required — the role key that needs to exist on the related resource (from the relation)
        - `on_resource` string, required — the resource key that needs to exist on the related role (from the relation)
        - `linked_by_relation` string, required — the relation key that needs to exist between the resource and the related resource
        - `when` PermitBackendSchemasSchemaDerivedRoleRuleDerivationSettings — Settings for a derived role or a derived role rule
          - `no_direct_roles_on_object` boolean — If true, the derived role or the specific rule will not apply if the resource has any direct role
    - `v1compat_settings` object
    - `v1compat_attributes` object
    - `key` string, required — A URL-friendly name of the role (i.e: slug). You will be able to query later using this key instead of the id (UUID) of the role.
    - `id` string, uuid, required — Unique id of the role
    - `organization_id` string, uuid, required — Unique id of the organization that the role belongs to.
    - `project_id` string, uuid, required — Unique id of the project that the role belongs to.
    - `environment_id` string, uuid, required — Unique id of the environment that the role belongs to.
    - `created_at` string, date-time, required — Date and time when the role was created (ISO_8601 format).
    - `updated_at` string, date-time, required — Date and time when the role was last updated/modified (ISO_8601 format).

## Other responses

- `422` — Validation Error

---

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