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

# Update a Role

> Changes a role's label and description. Anything you omit is left alone.

The role's `name` — the identifier in `{id}` — CANNOT be changed here or anywhere else; it is what grants point at. The permissions inside the role are not edited here either: use `POST /v1/roles/{id}/permissions` and its remove counterpart. So this endpoint cannot widen or narrow anybody's access, which is why it is the least dangerous call in the family.

Failures:
- `400` — a supplied member is malformed.
- `404` — no such role in your organization.
- `422 IDE-1062` — the change would set, alter or remove a `description` starting with `ri-declared:`, which belongs to the service that declared the role. Resending the current description unchanged is accepted.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



## OpenAPI

````yaml /en/openapi/v3-current/AM-identity.yaml patch /v1/roles/{id}
openapi: 3.1.0
info:
  contact:
    name: Lerian Studio
    url: https://lerian.studio
  description: OpenAPI 3.1 surface for the Access Manager identity component.
  license:
    name: Lerian Studio General License
  title: Plugin Access Manager — Identity API
  version: v1
servers:
  - url: https://identity.sandbox.lerian.net
security: []
tags:
  - description: >-
      M2M-only: each plugin declares its own permissions, roles and M2M
      contract, and the server reconciles them.
    name: Declarations
  - description: >-
      A tenant administrator's customers. Each partner holds what its
      credentials may DO (permissions, per product) and WHERE they may do it
      (scope, per product and dimension); an M2M application attached to one is
      confined to that intersection. Administrator-only: authorized on the
      "partners" resource, and every route resolves the owning organization from
      the caller's token.
    name: Partners
paths:
  /v1/roles/{id}:
    patch:
      tags:
        - Roles
      summary: Update a Role
      description: >-
        Changes a role's label and description. Anything you omit is left alone.


        The role's `name` — the identifier in `{id}` — CANNOT be changed here or
        anywhere else; it is what grants point at. The permissions inside the
        role are not edited here either: use `POST /v1/roles/{id}/permissions`
        and its remove counterpart. So this endpoint cannot widen or narrow
        anybody's access, which is why it is the least dangerous call in the
        family.


        Failures:

        - `400` — a supplied member is malformed.

        - `404` — no such role in your organization.

        - `422 IDE-1062` — the change would set, alter or remove a `description`
        starting with `ri-declared:`, which belongs to the service that declared
        the role. Resending the current description unchanged is accepted.

        - `503 IDE-0066` — the identity provider is unavailable (unreachable,
        too slow to answer, or failing). Nothing about the request was wrong;
        retry it later.
      operationId: updateRole
      parameters:
        - description: Role ID.
          in: path
          name: id
          required: true
          schema:
            description: Role ID.
            examples:
              - midaz-editor
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleUpdateInput'
              description: The role members to update.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Service Unavailable
      security:
        - BearerAuth: []
components:
  schemas:
    RoleUpdateInput:
      additionalProperties: false
      properties:
        description:
          examples:
            - An updated description
          type: string
        displayName:
          examples:
            - Updated Editor
          type: string
        isEnabled:
          examples:
            - true
          type: boolean
      type: object
    RoleResponse:
      additionalProperties: false
      properties:
        createdAt:
          examples:
            - '2026-06-24T10:00:00Z'
          type: string
        description:
          examples:
            - A custom editor role
          type: string
        groups:
          items:
            type: string
          type: array
        id:
          examples:
            - custom-editor
          type: string
        isEnabled:
          examples:
            - true
          type: boolean
        isSystem:
          examples:
            - false
          type: boolean
        name:
          examples:
            - Custom Editor
          type: string
        roles:
          items:
            type: string
          type: array
        users:
          items:
            type: string
          type: array
      type: object
    HTTPError:
      additionalProperties: false
      properties:
        code:
          type: string
        entityType:
          type: string
        err: {}
        message:
          type: string
        title:
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.