---
title: "Update a role's description"
url: "https://dev.developer-internal.sanofi.com/apis/plta-permissions-api-cbz/versions/88cdfef8-3b56-44ca-883d-5b15378e5a3a/operations/updateRole"
---

> Full API specification: https://dev.developer-internal.sanofi.com/apis/plta-permissions-api-cbz/versions/88cdfef8-3b56-44ca-883d-5b15378e5a3a.md

# Update a role's description

`PATCH` `/roles/{roleName}`

Operation ID: `updateRole`

Update a role's description. The role's name and scope (scopeAction, scopeResource) are immutable once created.

## Path parameters

- `roleName` (string, required) - The name of the role

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Success
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `500` - Internal Server Error

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Permission Administration API
  version: 1.5.0
servers:
  - url: https://dev.api.sanofi.com/permissions
paths:
  /roles/{roleName}:
    parameters:
      - description: The name of the role
        in: path
        name: roleName
        required: true
        schema:
          type: string
    patch:
      description: Update a role's description. The role's name and scope
        (scopeAction, scopeResource) are immutable once created.
      operationId: updateRole
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
              required:
                - description
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleDetails"
          description: Success
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      summary: Update a role's description
      tags:
        - Roles
security:
  - oauth: []
components:
  schemas:
    RoleDetails:
      allOf:
        - $ref: "#/components/schemas/Role"
        - properties:
            accessGrants:
              description: The access grants attached to this role.
              items:
                $ref: "#/components/schemas/AccessGrant"
              readOnly: true
              type: array
            adminGrants:
              description: The admin grants attached to this role.
              items:
                $ref: "#/components/schemas/AdminGrant"
              readOnly: true
              type: array
            members:
              description: The users attached to this role.
              items:
                $ref: "#/components/schemas/RoleMember"
              readOnly: true
              type: array
          type: object
      description: A role, along with its access grants, admin grants, and members.
    Role:
      description: A named bundle of access and admin grants, scoped to an action and
        a resource. All of a role's grants are always contained within this
        scope.
      properties:
        description:
          description: A human-readable description of the role's purpose.
          type: string
        roleName:
          description: The business identifier of the role.
          examples:
            - clintrials:study-reader
          type: string
        scopeAction:
          description: The action (with its hierarchy) that bounds this role's access and
            admin grants. Immutable once the role is created.
          examples:
            - read
          type: string
        scopeResource:
          description: The resource (with its hierarchy) that bounds this role's access
            and admin grants. Immutable once the role is created.
          examples:
            - clintrials
          type: string
      required:
        - roleName
        - scopeAction
        - scopeResource
      type: object
    AccessGrant:
      description: An access right (an action/resource pair) attached to a role. Every
        member of the role inherits it. The action and resource must be within
        the role's declared scope.
      properties:
        accessGrantId:
          description: The unique identifier of the access grant, mostly for deletion
            purpose.
          format: uuid
          readOnly: true
          type: string
        actionName:
          description: Name of the action.
          examples:
            - read_narrative
          type: string
        resourceName:
          description: Name of the resource.
          examples:
            - compound_1245
          type: string
        roleName:
          description: The name of the role this grant is attached to, as given in the path.
          readOnly: true
          type: string
      required:
        - actionName
        - resourceName
      type: object
    AdminGrant:
      description: An admin right (an operation, with optional action/resource
        restrictions) attached to a role. Every member of the role inherits it.
        The restrictions must be within the role's declared scope. The caller
        must already hold an admin right covering the exact operation and
        restrictions being granted.
      properties:
        actionRestriction:
          description: Name of the action that will restrict the action usable in this
            operation to a specific hierarchy, within the role's scope.
          examples:
            - write_narrative
            - read_compound
          type: string
        adminGrantId:
          description: The unique identifier of the admin grant, mostly for deletion
            purpose.
          format: uuid
          readOnly: true
          type: string
        operationName:
          description: Name of the operation.
          examples:
            - manageActions
            - manageResources
            - manageAccessRights
          type: string
        resourceRestriction:
          description: Name of the resource that will restrict the resource usable in this
            operation to a specific hierarchy, within the role's scope.
          examples:
            - compound_1245
            - study_1245
          type: string
        roleName:
          description: The name of the role this grant is attached to, as given in the path.
          readOnly: true
          type: string
      required:
        - operationName
      type: object
    RoleMember:
      description: A user attached to a role, inheriting all of its access and admin grants.
      properties:
        attachedAt:
          description: When the user was attached to the role.
          format: date-time
          readOnly: true
          type: string
        attachedBy:
          description: The id of the user (oid or username) who performed the attach, for
            audit purposes.
          readOnly: true
          type: string
        roleName:
          description: The name of the role, as given in the path.
          readOnly: true
          type: string
        userId:
          description: The id of the user, as stored in IDP. For Sanofi internal user, it
            would be the oid (Unique identifier of the user in Azure AD)
          readOnly: true
          type: string
      readOnly: true
      required:
        - roleName
        - userId
        - attachedAt
        - attachedBy
      type: object
    BadRequestError:
      properties:
        debugId:
          description: A unique request identifier for correlation purposes.
          example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
          type: string
        detail:
          description: Error detail
          type: string
        errors:
          description: A list of errors that occurred
          items:
            $ref: "#/components/schemas/BadRequestDetails"
          type: array
        instance:
          default: unknown
          description: URI that identifies the specific occurrence of the problem
          example: https://api.dev.accelerator.sanofi/planets/v1/planets/
          type: string
        status:
          description: HTTP status code
          enum:
            - 400
          type: number
        title:
          description: Human-readable identifier
          type: string
        type:
          description: URI that identifies the type of error that occurred
          example: https://backstage.prod.accelerator.sanofi/docs/default/component/sanofi-accelerator-api-rules/errors-bad-request
          type: string
      required:
        - type
        - title
        - status
        - debugId
        - detail
      type: object
    UnauthorizedError:
      properties:
        debugId:
          description: A unique request identifier for correlation purposes.
          example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
          type: string
        detail:
          description: Error detail
          enum:
            - You are not authorized to access this resource
          type: string
        status:
          description: HTTP status code
          enum:
            - 401
          type: number
        title:
          description: Human-readable identifier
          enum:
            - Unauthorized
          type: string
        type:
          description: URI that identifies the type of error that occurred
          example: https://backstage.prod.accelerator.sanofi/docs/default/component/sanofi-accelerator-api-rules/errors-unauthorized
          type: string
      required:
        - type
        - title
        - status
        - debugId
        - detail
      type: object
    ForbiddenError:
      properties:
        debugId:
          description: A unique request identifier for correlation purposes.
          example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
          type: string
        detail:
          description: Error detail
          enum:
            - You don't have the permission to access this resource
          type: string
        status:
          description: HTTP status code
          enum:
            - 403
          type: number
        title:
          description: Human-readable identifier
          enum:
            - Forbidden
          type: string
        type:
          description: URI that identifies the type of error that occurred
          example: https://backstage.prod.accelerator.sanofi/docs/default/component/sanofi-accelerator-api-rules/errors-forbidden
          type: string
      required:
        - type
        - title
        - status
        - debugId
        - detail
      type: object
    NotFoundError:
      properties:
        debugId:
          description: A unique request identifier for correlation purposes.
          example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
          type: string
        detail:
          description: Error detail
          type: string
        status:
          description: HTTP status code
          enum:
            - 404
          type: number
        title:
          description: Human-readable identifier
          enum:
            - Not Found
          type: string
        type:
          description: URI that identifies the type of error that occurred
          example: https://backstage.prod.accelerator.sanofi/docs/default/component/sanofi-accelerator-api-rules/errors-not-found
          type: string
      required:
        - type
        - title
        - status
        - debugId
        - detail
      type: object
    InternalServerError:
      description: Object describing the error format expected in API responses. Based
        on [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457)
      properties:
        debugId:
          description: A unique request identifier for correlation purposes. [Trace
            Context RFC](https://www.w3.org/TR/trace-context/)
          example: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
          type: string
        detail:
          description: More information about the specific problem, and if it's
            appropriate also steps to correct it. For example information about
            a form validation problem
          example: The service is currently unavailable due to an unexpected error
          type: string
        status:
          description: HTTP status code
          example: 500
          type: number
        title:
          description: Human-readable identifier, usually the same type field should have
            the same title field
          example: Internal Server Error
          type: string
        type:
          description: URI that identifies the type of error that occured
          example: https://backstage.prod.accelerator.sanofi/docs/default/component/sanofi-accelerator-api-rules/errors-internal/
          type: string
      required:
        - type
        - title
        - status
        - debugId
        - detail
      type: object
    BadRequestDetails:
      properties:
        detail:
          description: Error detail
          example: Planet area must be a valid number
          type: string
        pointer:
          description: Pointer to the field that has the error
          example: "#/planet/area"
          type: string
        rejectedValue:
          description: The value that was rejected
          example: NaN
          type: string
      required:
        - detail
        - pointer
      type: object
  responses:
    "400":
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BadRequestError"
      description: Bad Request
    "401":
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UnauthorizedError"
      description: Unauthorized
    "403":
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
      description: Forbidden
    "404":
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NotFoundError"
      description: Not Found
    "500":
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InternalServerError"
      description: Internal Server Error
  securitySchemes:
    oauth:
      bearerFormat: JWT
      scheme: bearer
      type: http
```