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

# Edit a role's grant map

> Edit a role's per-tag grant map + description (the base-tier jq is seed-fixed, not
editable here). Admin-only; guards the reserved ``admin`` role and the block-downgrade
of any allow_all role. Both inputs are omit-means-keep — an absent ``grants``/
``description`` preserves the stored value, so a description-only edit never wipes the
grant map. Validates a supplied grant map before persist; LIVE — the edit changes every
holder's reach on their next request via the policy-version bump. Audits.



## OpenAPI

````yaml /openapi.json put /api/auth/roles/{name}
openapi: 3.1.0
info:
  description: The operator HTTP surface served under /api/*.
  title: tai42-skeleton API
  version: 0.1.1
servers: []
security: []
paths:
  /api/auth/roles/{name}:
    put:
      tags:
        - access-control
      summary: Edit a role's grant map
      description: >-
        Edit a role's per-tag grant map + description (the base-tier jq is
        seed-fixed, not

        editable here). Admin-only; guards the reserved ``admin`` role and the
        block-downgrade

        of any allow_all role. Both inputs are omit-means-keep — an absent
        ``grants``/

        ``description`` preserves the stored value, so a description-only edit
        never wipes the

        grant map. Validates a supplied grant map before persist; LIVE — the
        edit changes every

        holder's reach on their next request via the policy-version bump.
        Audits.
      operationId: put_api_auth_roles_name
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data: {}
                required:
                  - data
                type: object
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Malformed request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid api key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Resource not found.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    RoleUpdate:
      description: >-
        The edit-role request body: only the per-tag grant map + description are
        editable;

        the base-tier jq / base_tier are seed-fixed and rejected on any change
        attempt. Both

        fields are omit-means-keep — an absent ``grants`` (``None``) preserves
        the stored grant

        map (it is never silently wiped), and an absent ``description``
        preserves the stored

        description.
      properties:
        description:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Description
        grants:
          anyOf:
            - additionalProperties:
                enum:
                  - none
                  - read
                  - write
                type: string
              type: object
            - type: 'null'
          default: null
          title: Grants
      title: RoleUpdate
      type: object
    Error:
      properties:
        error:
          type: string
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````