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

# putRole

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

Create or update role

## Path parameters

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

## Request body

- union
  - object — A standard user role. Must be explicitly assigned to users.
    - `grants` object[], 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
      - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role
        - `action` string, required
        - `resource` string
        - `effect` 'allow' | 'deny'
        - `conditions` GrantCondition[]
          - union
            - object — Check if attribute equals to any of the values
              - …
            - 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.
              - …
    - `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
    - `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.
  - object — A role automatically applied to all users in an organization.
    - `grants` object[], 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
      - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role
        - `action` string, required
        - `resource` string
        - `effect` 'allow' | 'deny'
        - `conditions` GrantCondition[]
          - union
            - object — Check if attribute equals to any of the values
              - …
            - 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.
              - …
    - `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
    - `pricing_tier` string — The pricing tier of the organization this root role is based on
  - object — A role that can be assigned to users in other organizations for sharing purposes.
    - `grants` object[], 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
      - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role
        - `action` string, required
        - `resource` string
        - `effect` 'allow' | 'deny'
        - `conditions` GrantCondition[]
          - union
            - object — Check if attribute equals to any of the values
              - …
            - 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.
              - …
    - `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
  - object — A role that appears in another organization's role list that can be assigned but not modified by the partner organization.
    - `grants` object[], 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
      - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role
        - `action` string, required
        - `resource` string
        - `effect` 'allow' | 'deny'
        - `conditions` GrantCondition[]
          - union
            - object — Check if attribute equals to any of the values
              - …
            - 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.
              - …
    - `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
    - `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.
  - object — A role that is applied to end customers and installers using the Portals
    - `grants` object[], 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
      - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role
        - `action` string, required
        - `resource` string
        - `effect` 'allow' | 'deny'
        - `conditions` GrantCondition[]
          - union
            - object — Check if attribute equals to any of the values
              - …
            - 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.
              - …
    - `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

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

## Other responses

- `400` — Bad Request - Invalid role configuration
- `404` — Not Found - Parent role does not exist

---

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