---
title: "Create Role"
method: POST
path: "/v2/schema/{proj_id}/{env_id}/roles"
tags: ["Roles"]
---

# Create Role

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

Creates a new tenant role.

## 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").

## Request body

- RoleCreate
  - `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.
  - `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` DerivedRoleBlockEdit
    - `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
    - `users_with_role` DerivedRoleRuleCreate[] — the rules of the derived role
      - `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
  - `v1compat_is_built_in` boolean

## Response `200`

Successful Response

- 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)