"/api/v4/custom_profile_attributes/fields":
    get:
      tags:
        - custom profile attributes
      summary: List all the Custom Profile Attributes fields
      description: |
        List all the Custom Profile Attributes fields.

        __Minimum server version__: 10.5

        ##### Permissions
        Must be authenticated.
      operationId: ListAllCPAFields
      responses:
        "200":
          description: Custom Profile Attributes fetch successful. Result may be empty.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PropertyField"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      tags:
        - custom profile attributes
      summary: Create a Custom Profile Attribute field
      description: |
        Create a new Custom Profile Attribute field on the system.

        __Minimum server version__: 10.5

        ##### Permissions
        Must have `manage_system` permission.
      operationId: CreateCPAField
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - type
              properties:
                name:
                  type: string
                  description: >
                    The internal identifier for this attribute. Must match
                    `^[A-Za-z_][A-Za-z0-9_]*$` and must not be a CEL reserved
                    word (true, false, null, in, as, break, const, continue, else,
                    for, function, if, import, let, loop, package, namespace,
                    return, var, void, while). This name is used in ABAC policy
                    expressions as `user.attributes.<name>`.
                type:
                  type: string
                attrs:
                  type: object
                  properties:
                    visibility:
                      type: string
                      description: "Visibility of the attribute"
                      enum: ["hidden", "when_set", "always"]
                      default: "when_set"
                    sort_order:
                      type: number
                      description: "Sort order for displaying this attribute"
                    options:
                      type: array
                      description: "Options for select/multiselect fields"
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          color:
                            type: string
                    value_type:
                      type: string
                      description: "Type of text value"
                      enum: ["email", "url", "phone"]
                    ldap:
                      type: string
                      description: "LDAP attribute for syncing"
                    saml:
                      type: string
                      description: "SAML attribute for syncing"
                    protected:
                      type: boolean
                      description: "If true, the field is read-only and cannot be modified."
                    source_plugin_id:
                      type: string
                      description: "The ID of the plugin that created this field. This attribute cannot be changed."
                    access_mode:
                      type: string
                      description: "Access mode of the field"
                      enum: ["", "source_only", "shared_only"]
                      default: ""
                    display_name:
                      type: string
                      description: >
                        Human-readable label shown in the UI. Defaults to the field
                        `name` when omitted or empty. Maximum 255 characters.
      responses:
        "201":
          description: Custom Profile Attribute field creation successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PropertyField"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: >
            Validation error. Returned when `name` does not match the
            required identifier pattern, is a CEL reserved word, or when
            `attrs.display_name` exceeds 255 characters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppError"

  "/api/v4/custom_profile_attributes/fields/{field_id}":
    patch:
      tags:
        - custom profile attributes
      summary: Patch a Custom Profile Attribute field
      description: |
        Partially update a Custom Profile Attribute field by providing
        only the fields you want to update. Omitted fields will not be
        updated. The fields that can be updated are defined in the
        request body, all other provided fields will be ignored.

        **Note:** Fields with `attrs.protected = true` cannot be
        modified and will return an error.

        __Minimum server version__: 10.5

        ##### Permissions
        Must have `manage_system` permission.
      operationId: PatchCPAField
      parameters:
        - name: field_id
          in: path
          description: Custom Profile Attribute field GUID
          required: true
          schema:
            type: string
      requestBody:
        description: Custom Profile Attribute field that is to be updated
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >
                    New name for the attribute. When changed, must match
                    `^[A-Za-z_][A-Za-z0-9_]*$` and must not be a CEL reserved
                    word. Pre-existing fields with non-conforming names remain
                    patchable on all other attributes; the validation only fires
                    when `name` actually changes.
                type:
                  type: string
                attrs:
                  type: object
                  properties:
                    visibility:
                      type: string
                      description: "Visibility of the attribute"
                      enum: ["hidden", "when_set", "always"]
                      default: "when_set"
                    sort_order:
                      type: number
                      description: "Sort order for displaying this attribute"
                    options:
                      type: array
                      description: "Options for select/multiselect fields"
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          color:
                            type: string
                    value_type:
                      type: string
                      description: "Type of text value"
                      enum: ["email", "url", "phone"]
                    ldap:
                      type: string
                      description: "LDAP attribute for syncing"
                    saml:
                      type: string
                      description: "SAML attribute for syncing"
                    protected:
                      type: boolean
                      description: "If true, the field is read-only and cannot be modified."
                    source_plugin_id:
                      type: string
                      description: "The ID of the plugin that created this field. This attribute cannot be changed."
                    access_mode:
                      type: string
                      description: "Access mode of the field"
                      enum: ["", "source_only", "shared_only"]
                      default: ""
                    display_name:
                      type: string
                      description: >
                        Human-readable label shown in the UI. Maximum 255 characters.
      responses:
        "200":
          description: Custom Profile Attribute field patch successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PropertyField"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: >
            Validation error. Returned when a `name` change does not match
            the required identifier pattern, is a CEL reserved word, or
            when `attrs.display_name` exceeds 255 characters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppError"

    delete:
      tags:
        - custom profile attributes
      summary: Delete a Custom Profile Attribute field
      description: |
        Marks a Custom Profile Attribute field and all its values as
        deleted.

        __Minimum server version__: 10.5

        ##### Permissions
        Must have `manage_system` permission.
      operationId: DeleteCPAField
      parameters:
        - name: field_id
          in: path
          description: Custom Profile Attribute field GUID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Custom Profile Attribute field deletion successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusOK"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  "/api/v4/custom_profile_attributes/values":
    patch:
      tags:
        - custom profile attributes
      summary: Patch Custom Profile Attribute values
      description: |
        Partially update a set of values on the requester's Custom
        Profile Attribute fields by providing only the information you
        want to update. Omitted fields will not be updated. The fields
        that can be updated are defined in the request body, all other
        provided fields will be ignored.

        **Note:** Values for fields with `attrs.protected = true` cannot be
        updated and will return an error.

        __Minimum server version__: 10.5

        ##### Permissions
        Must be authenticated.
      operationId: PatchCPAValues
      requestBody:
        description: Custom Profile Attribute values that are to be updated
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  value:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
      responses:
        "200":
          description: Custom Profile Attribute values patch successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    value:
                      oneOf:
                        - type: string
                        - type: array
                          items:
                            type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  "/api/v4/custom_profile_attributes/group":
    get:
      tags:
        - custom profile attributes
      summary: Get Custom Profile Attribute property group data
      description: |
        Get the property group used for Custom Profile Attributes.

        __Minimum server version__: 10.8

        ##### Permissions
        Must be authenticated.
      operationId: GetCPAGroup
      responses:
        "200":
          description: Group fetch successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the custom profile attributes group
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  "/api/v4/users/{user_id}/custom_profile_attributes":
    get:
      tags:
        - custom profile attributes
      summary: List Custom Profile Attribute values
      description: |
        List all the Custom Profile Attributes values for specified user.

        __Minimum server version__: 10.5

        ##### Permissions
        Must have `view members` permission.
      operationId: ListCPAValues
      parameters:
        - name: user_id
          in: path
          description: User GUID
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Custom Profile Attribute values fetch successful. Result may be empty.
          content:
            application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  field_id:
                    type: string
                  value:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    patch:
      tags:
        - custom profile attributes
      summary: Update custom profile attribute values for a user
      description: |
        Update Custom Profile Attribute field values for a specific user.

        **Note:** Values for fields with `attrs.protected = true` cannot be
        updated and will return an error.

        __Minimum server version__: 11

        ##### Permissions
        Must have permission to edit the user. Users can only edit their own CPA values unless they are system administrators.
      parameters:
        - name: user_id
          in: path
          description: User GUID
          required: true
          schema:
            type: string
      operationId: PatchCPAValuesForUser
      requestBody:
        description: Custom Profile Attribute values that are to be updated
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  value:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
      responses:
        '200':
          description: Custom profile attribute values updated successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    value:
                      oneOf:
                        - type: string
                        - type: array
                          items:
                            type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'