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

# Update a role

> Changes a custom role's name and/or permissions. Built-in roles cannot be changed.

Requires a role with the `org.members.manage` permission in the organization given by `org_id`.



## OpenAPI

````yaml /openapi/hub-by-tag/hub-organizations.yaml post /v1/orgs/update_role
openapi: 3.0.3
info:
  title: 'CliqHub API: Organizations'
  version: 1.0.0
  description: >-
    An organization owns realms, teams (through its scopes) and people. Every
    organization

    has four built-in roles, **Owner**, **Admin**, **Operator** and **Member**,
    and can define

    its own: a role is a named set of permissions (List permissions shows them
    all). Owners can

    do everything; `org.delete` and `org.transfer` belong to owners only.


    **Scopes** are the organization's package namespaces (`@acme`,
    `@acme-labs`): teams are

    published under a scope, and only the scope's members may publish to it. The
    organization's

    **team library** lists the teams its realms may use. Organization-wide
    notification rules

    also live here.


    People join an organization through Send an invitation. Organizations are
    created by site

    administrators for their future owner.
servers:
  - url: https://{host}
    variables:
      host:
        default: cliqhub.io
        description: CliqHub host
security: []
tags:
  - name: Organizations
    description: >-
      An organization owns realms, teams (through its scopes) and people. Every
      organization

      has four built-in roles, **Owner**, **Admin**, **Operator** and
      **Member**, and can define

      its own: a role is a named set of permissions (List permissions shows them
      all). Owners can

      do everything; `org.delete` and `org.transfer` belong to owners only.


      **Scopes** are the organization's package namespaces (`@acme`,
      `@acme-labs`): teams are

      published under a scope, and only the scope's members may publish to it.
      The organization's

      **team library** lists the teams its realms may use. Organization-wide
      notification rules

      also live here.


      People join an organization through Send an invitation. Organizations are
      created by site

      administrators for their future owner.
paths:
  /v1/orgs/update_role:
    post:
      tags:
        - Organizations
      summary: Update a role
      description: >-
        Changes a custom role's name and/or permissions. Built-in roles cannot
        be changed.


        Requires a role with the `org.members.manage` permission in the
        organization given by `org_id`.
      operationId: POST_v1_orgs_update_role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                  description: Org UUID
                role_id:
                  type: string
                  format: uuid
                  description: Present for update; omit to create
                slug:
                  type: string
                  minLength: 1
                  maxLength: 49
                  description: URL-safe role identifier within the org; required on create
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Human-readable role name
                permissions:
                  type: array
                  items:
                    type: string
                  description: Permission slugs to grant
              required:
                - org_id
            examples:
              default:
                value:
                  org_id: 2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f
                  role_id: 8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e
                  permissions:
                    - teams.publish
                    - teams.install
                    - runs.view
                    - runs.cancel
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                properties:
                  ok:
                    type: boolean
                    enum:
                      - true
                    description: Always `true` on success.
                  data:
                    type: object
                    properties:
                      role:
                        $ref: '#/components/schemas/RoleData'
              example:
                ok: true
                data:
                  role:
                    id: 8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e
                    org_id: 2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f
                    slug: release-manager
                    name: Release manager
                    permissions:
                      - teams.publish
                      - teams.install
                      - runs.view
                    is_system: false
                    is_default: false
                    member_count: 2
                    created_at: '2026-09-01T00:00:00Z'
        '401':
          description: >-
            `unauthorized`: No `Authorization` header, or the token is
            malformed, expired or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                unauthorized:
                  summary: unauthorized
                  value:
                    ok: false
                    error:
                      code: unauthorized
                      message: Authentication required
        '403':
          description: >-
            `forbidden`: You are a member of the organization but your role
            lacks the required permission, or a daemon token was used.


            `forbidden`: The role is a built-in role.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                forbidden:
                  summary: forbidden
                  value:
                    ok: false
                    error:
                      code: forbidden
                      message: You do not have access to do this
                forbidden (endpoint):
                  summary: forbidden (endpoint)
                  value:
                    ok: false
                    error: System roles cannot be edited
                    code: forbidden
        '404':
          description: >-
            `not_found`: The organization does not exist or you are not a
            member. CliqHub answers 404, not 403, so it does not reveal which.


            `not_found`: The organization has no role with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                not_found:
                  summary: not_found
                  value:
                    ok: false
                    error:
                      code: not_found
                      message: Not found
                not_found (endpoint):
                  summary: not_found (endpoint)
                  value:
                    ok: false
                    error: Role not found
                    code: not_found
        '422':
          description: >-
            `invalid_params`: The name is empty, or a permission is unknown or
            owner-only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                invalid_params:
                  summary: invalid_params
                  value:
                    ok: false
                    error: Unknown permission 'teams.deploy'
                    code: invalid_params
        '500':
          description: >-
            `internal_error`: An unexpected server fault. Retry later; if it
            persists, report it with the time of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                internal_error:
                  summary: internal_error
                  value:
                    ok: false
                    error: Internal server error
                    code: internal_error
      security:
        - BearerAuth: []
components:
  schemas:
    RoleData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Role UUID
        org_id:
          type: string
          format: uuid
          description: Owning org UUID
        slug:
          type: string
          description: URL-safe role identifier within the org
        name:
          type: string
          description: Human-readable role name
        permissions:
          type: array
          items:
            type: string
          description: Permission slugs granted by this role
        is_system:
          type: boolean
          description: True for built-in roles that cannot be deleted
        is_default:
          type: boolean
          description: True if assigned to new org members automatically
        member_count:
          type: integer
          description: Number of org members currently assigned this role
        created_at:
          type: string
          description: ISO timestamp of role creation
      required:
        - id
        - org_id
        - slug
        - name
        - permissions
        - is_system
        - is_default
        - member_count
        - created_at
    HubErr:
      type: object
      required:
        - ok
        - error
      description: >-
        Every failure. Route-policy denials (401/403/404, and 400 when neither
        realm_id nor org_id was sent) answer `error` as `{ code, message }`;
        errors raised by the endpoint answer `error` as the message with the
        code beside it in `code`. Every error has a code. See
        [Errors](/hub-api/errors).
      properties:
        ok:
          type: boolean
          description: Always false on error
        error:
          description: The message, or `{ code, message }` for an access denial.
          oneOf:
            - type: string
            - type: object
              required:
                - code
                - message
              properties:
                code:
                  type: string
                message:
                  type: string
        code:
          type: string
          description: Stable error code of an endpoint error.
        details:
          type: object
          additionalProperties: true
          description: Structured detail, when there is some.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cliq_tok_* | cliq_dt_*
      description: >-
        User PAT (`cliq_tok_…`, including session-scoped) or realm token
        (`cliq_dt_…`).

````

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